Next: Module structure
Up: Style Guide
Previous: Style Guide
Index
- 1.
- There is one directory containing all code and its documentation (using sub-directories).
- 2.
- Filenames are of form [a-z][a-z_]+ with extension .ecl .
- 3.
- One file per module, one module per file.
- 4.
- Each module is documented with comment directives.
- 5.
- All required interfaces are defined in separate spec files which are included in the source with a comment include directive. This helps to separate specification and implementation code.
- 6.
- The actual data of the problem is loaded dynamically from the Java interface; for stand-alone testing data files from the data directory are included in the correct modules.
- 7.
- The file name is equal to the module name.
- 8.
- Predicate names are of form [a-z][a-z_]*[0-9]* . Underscores are used to separate words. Digits should only be used at the end of the name. Words should be English.
- 9.
- Variable names are of form [A-Z_][a-zA-Z]*[0-9]* . Separate words with capital letters. Digits should only be used at the end. Words should be English.
- 10.
- The code should not contain singleton variables, unless their names start with _. The final program may not generate singleton warnings.
- 11.
- Each exported predicate is documented with a comment directive.
- 12.
- Clauses for a predicate must be consecutive.
- 13.
- Base clauses should be stated before recursive cases.
- 14.
- Input arguments should be placed before output arguments.
- 15.
- Predicates which are not exported should be documented with a single line comment. It is possible to use comment directives instead.
- 16.
- The sequence of predicates in a file is top-down with a (possibly empty) utility section at the end.
- 17.
- All structures are defined in one file (e.g. flow_structures.ecl) and are documented with comment directives.
- 18.
- Terms should not be used; instead use named structures.
- 19.
- When possible, use do-loops instead of recursion.
- 20.
- When possible, use separate predicates instead of disjunction or if-then-else.
- 21.
- There should be no nested if-then-else construct in the code.
- 22.
- All input data should be converted into structures at the beginning of the program; there should be no direct access to the data afterwards.
- 23.
- All integer constants should be parametrized via facts. There should be no integer values (others than 0 and 1) in rules.
- 24.
- The final code should not use failure-loops; they are acceptable for debugging or testing purposes.
- 25.
- Cuts (!) should be inserted only to eliminate clearly defined choice points.
- 26.
- The final code may not contain open choice points, except for alternative solutions that still can be explored. This is verified with the tracer tool in the debugger.
- 27.
- Customizable data facts should always be at the end of a file; their use is deprecated.
- 28.
- The predicate member/2 should only be used where backtracking is required; otherwise use memberchk/2 to avoid hidden choice points.
- 29.
- The final code may not contain dead code except in the file/module unsupported.ecl. This file should contain all program pieces which are kept for information/debugging, but which are not part of the deliverable.
- 30.
- The test set(s) should exercise 100 percent of the final code. Conformity is checked with the line coverage profiler.
- 31.
- Explicit unification (=/2) should be replaced with unification inside terms where possible.
- 32.
- There is a top-level file (top.ecl) which can be used to generated all on-line documentation automatically.
- 33.
- For each module, a module diagram is provided.
- 34.
- For the top-level files, component diagrams are provided.
- 35.
- Don't use ','/2 to make tuples.
- 36.
- Don't use lists to make tuples.
- 37.
- Avoid append/3 where possible, use accumulators instead.
Next: Module structure
Up: Style Guide
Previous: Style Guide
Index
Warwick Harvey
2004-08-07