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