E.1 Style rules
-
There is one directory containing all code and its documentation (using
sub-directories).
- Filenames are of the form [a-z][a-z_]+ with
the 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 the 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 the 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 must 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 clauses instead of
disjunction or if-then-else.
- There should be no nested if-then-else constructs 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 creating redundant 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.