1% BEGIN LICENSE BLOCK
2% Version: CMPL 1.1
3%
4% The contents of this file are subject to the Cisco-style Mozilla Public
5% License Version 1.1 (the "License"); you may not use this file except
6% in compliance with the License.  You may obtain a copy of the License
7% at www.eclipse-clp.org/license.
8%
9% Software distributed under the License is distributed on an "AS IS"
10% basis, WITHOUT WARRANTY OF ANY KIND, either express or implied.  See
11% the License for the specific language governing rights and limitations
12% under the License.
13%
14% The Original Code is  The ECLiPSe Constraint Logic Programming System.
15% The Initial Developer of the Original Code is  Cisco Systems, Inc.
16% Portions created by the Initial Developer are
17% Copyright (C) 2006 Cisco Systems, Inc.  All Rights Reserved.
18%
19% Contributor(s):
20%
21% END LICENSE BLOCK
22
23\chapter{Style Guide}
24%HEVEA\cutdef[1]{section}
25\label{styleguide}
26
27Every {\eclipse} programming project should adopt a number of style rules.
28This appendix gives only a sample set of rules, which can serve as a guideline.
29Project teams should adapt them to their own needs and taste.
30
31\section{Style rules}
32\begin{enumerate}
33\item  There is one directory containing all code and its documentation (using
34  sub-directories).
35\item  Filenames\index{file name} are of the form \notation{[a-z][a-z_]+} with
36  the extension \notation{.ecl}.
37\item  One file per module, one module per file.
38\item  Each module is documented with comment directives.
39\item  All required interfaces are defined in separate spec files which are
40  included in the source with a \emph{comment include} directive. This helps to
41  separate specification and implementation code.
42\item  The actual data of the problem is loaded dynamically from the Java
43  interface; for stand-alone testing data files from the data directory are
44  included in the correct modules.
45\item  The file name is equal to the module name.
46\item  Predicate names\index{predicate name} are of the form
47  \notation{[a-z][a-z_]*[0-9]*}. Underscores are used to separate words. Digits
48  should only be used at the  end of the name. Words should be English.
49\item  Variable names\index{variable name} are of the form
50  \notation{[A-Z_][a-zA-Z]*[0-9]*}. Separate words with capital letters. Digits
51  should only be used at the end. Words should be English.
52\item  The code should not contain singleton variables\index{singleton}, unless
53  their names start with \notation{_}. The final program must not generate
54  singleton warnings.
55\item  Each exported predicate is documented with a comment
56  directive\index{comment directive}.
57\item  Clauses for a predicate must be consecutive.
58\item  Base clauses should be stated before recursive cases.
59\item  Input arguments should be placed before output arguments.
60\item  Predicates which are not exported should be documented with a single line
61  comment. It is possible to use comment directives instead.
62\item  The sequence of predicates in a file is top-down with a (possibly empty)
63  utility section at the end.
64\item  All structures are defined in one file (e.g.,
65  \notation{flow_structures.ecl}) and are documented with comment directives.
66\item  Terms should not be used; instead use named
67  structures\index{named structure}.
68\item  When possible, use do-loops instead of recursion.
69\item  When possible, use separate clauses instead of
70  disjunction\index{disjunction} or if-then-else.
71\item  There should be no nested if-then-else\index{if then else} constructs in
72  the code.
73\item  All input data should be converted into structures at the beginning of
74  the program; there should be no direct access to the data afterwards.
75\item  All integer constants\index{integer constants} should be parametrized via
76  facts. There should be no integer values (others than 0 and 1) in rules.
77\item  The final code should not use failure-loops\index{failure loop}; they are
78  acceptable for debugging or testing purposes.
79\item  Cuts (\notation{!})\index{cut} should be inserted only to eliminate
80  clearly defined choice points.
81\item  The final code may not contain open choice points, except for alternative
82  solutions that still can be explored. This is verified with the tracer tool in
83  the debugger.
84\item  Customizable data facts should always be at the end of a file; their use
85  is deprecated.
86\item  The predicate \predspecidx{member/2} should only be used
87  where backtracking is required; otherwise use
88  \predspecidx{memberchk/2} to avoid creating redundant choice
89  points.
90\item  The final code may not contain \Index{dead code} except in the
91  file/module \notation{unsupported.ecl}. This file should contain all program
92  pieces which are kept for information/debugging, but which are not part of the
93  deliverable.
94\item  The test set(s) should exercise 100 percent of the final code. Conformity
95  is checked with the line coverage profiler.
96\item  Explicit unification (\predspecidx{=/2}) should be replaced with
97  unification inside terms where possible.
98\item  There is a top-level file (\notation{top.ecl}) which can be used to
99  generated all on-line documentation automatically.
100\item  For each module, a module diagram is provided.
101\item  For the top-level files, component diagrams are provided.
102\item  Don't use \predspecidx{','/2} to make tuples.
103\item  Don't use lists to make tuples.
104\item  Avoid \predspecidx{append/3} where possible, use accumulators instead.
105\end{enumerate}
106
107\section{Module structure}
108The general form of a module is:
109
110\begin{enumerate}
111\item  module definition
112\item  module comment or inclusion of a spec file
113\item  exported/reexported predicates
114\item  used modules
115\item  used libraries
116\item  local variable definitions
117\item  other global operations and settings
118\item  predicate definitions
119\end{enumerate}
120
121\section{Predicate definition}
122The general form of a predicate definition is:
123
124\begin{enumerate}
125\item  predicate comment directive
126\item  mode declaration
127\item  predicate body
128\end{enumerate}
129
130%HEVEA\cutend
131