Previous Up Next

Appendix A  Style Guide

A.1  Style rules

  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 star with capital letters. Words should be English. The plural should be used for lists and other collections. Digits should only be used at the end to distinguish different versions of the same conceptual thing.
  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 numeric constants should be parametrized via facts. There should be no numeric values (other 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 (document.ecl) which can be used to generated all on-line documentation automatically.
  33. Don’t use ’,’/2 to make tuples.
  34. Don’t use lists to make tuples.
  35. Avoid append/3 where possible, use accumulators instead.

A.2  Module structure

The general form of a module is:

  1. module definition
  2. module comment or inclusion of a spec file
  3. exported/reexported predicates
  4. used modules
  5. used libraries
  6. local variable definitions
  7. other global operations and settings
  8. predicate definitions

A.3  Predicate definition

The general form of a predicate definition is:

  1. predicate comment directive
  2. mode declaration
  3. predicate body
Previous Up Next