E.1 Style rules
-
There is one directory containing all code and its documentation (using sub-directories).
- Filenames are of form [a-z][a-z_]+ with extension .ecl .
- One file per module, one module per file.
- Each module is documented with comment directives.
- 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.
- 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.
- The file name is equal to the module name.
- 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.
- 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.
- The code should not contain singleton variables, unless their names start with _. The final program may not generate singleton warnings.
- Each exported predicate is documented with a comment directive.
- Clauses for a predicate must be consecutive.
- Base clauses should be stated before recursive cases.
- Input arguments should be placed before output arguments.
- Predicates which are not exported should be documented with a single line comment. It is possible to use comment directives instead.
- The sequence of predicates in a file is top-down with a (possibly empty) utility section at the end.
- All structures are defined in one file (e.g. flow_structures.ecl) and are documented with comment directives.
- Terms should not be used; instead use named structures.
- When possible, use do-loops instead of recursion.
- When possible, use separate predicates instead of disjunction or if-then-else.
- There should be no nested if-then-else construct in the code.
- All input data should be converted into structures at the beginning of the program; there should be no direct access to the data afterwards.
- All integer constants should be parametrized via facts. There should be no integer values (others than 0 and 1) in rules.
- The final code should not use failure-loops; they are acceptable for debugging or testing purposes.
- Cuts (!) should be inserted only to eliminate clearly defined choice points.
- 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.
- Customizable data facts should always be at the end of a file; their use is deprecated.
- The predicate member/2 should only be used where backtracking is required; otherwise use memberchk/2 to avoid hidden choice points.
- 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.
- The test set(s) should exercise 100 percent of the final code. Conformity is checked with the line coverage profiler.
- Explicit unification (=/2) should be replaced with unification inside terms where possible.
- There is a top-level file (top.ecl) which can be used to generated all on-line documentation automatically.
- For each module, a module diagram is provided.
- For the top-level files, component diagrams are provided.
- Don’t use ’,’/2 to make tuples.
- Don’t use lists to make tuples.
- Avoid append/3 where possible, use accumulators instead.