1 Purpose
The purpose of this document is to present a policy to control the
quality and nature of written code during the
SCHEMESTATION project.
Another aim is to make it possible to automatically find description
of functions in code and use them as part of the documentation.
Furthermore, the
code-browser utility (documentated in Code-Browser Utility) will
be used to search and browse the code, which set some minor restrictions.
2 High-level objectives
The coding policy presented here is designed to meet the following
objectives:
- The coding style must be consistent throughout the project.
The author of a piece of code should not be able to be
deduced on the basis of the style of the piece only.
- Code must be as self-explanatory as possible.
- Internal integrity tests in form of
checked pre- and post-conditions
and other similar mechanisms must be used in order to
spot possible faults in the software as early as possible.
- Code must be documented. This is aided by a separate utility, that
extracts the description of the functions and data structures from the
code.
- The structure of the code must be modular and easily understood.
3 C coding policy
3.1 Lexical conventions
- The language used is ANSI C.
- The maximum line length is 78 characters.
- Opening and closing curly brackets must be placed on lines
of their own.
- Every sentence must be put on a line of its own.
- Every label must be put on a line of its own.
- Indentation style is the default style in Emacs C-mode.
- Variable names must be mnemonic, except for standard loop variables
etc. The name of a variable
must match the regexp [a-z_0-9]+.
- typedef and enum
must be used in place of #define when
possible.
- Type names must be mnemonic and match the regexp
[A-Z][a-zA-Z]+.
- #define'd macro names must match the regexp
[A-Z_]+.
- An adequate description of each function, its return value and
arguments is placed in comment straight before the defination of the
function in header file.
- Whitespace is required
- on the both sides of any binary operator except ->
(pointer field dereference) and . (dot);
- after a reserved keyword such as if, while etc.; and
- after a comma.
- Whitespace is not allowed
- after the function name in a function call;
- before a postfix or after a prefix operator;
- before a square bracket;
- after an opening parenthesis;
- after any unary operator; nor
- before or after -> or . (dot).
3.2 Structural conventions
- Header files must not create cyclical dependencies.
- Every .c file includes whatever it needs.
- Every .h includes only what is exactly necessary for
the definitions in the file to be self-contained.
- Header files must be protected by an #ifdef ... construct.
- Declare functions internal to a .c file as ``static''
in order to denote them as such.
- Do not use the keyword external before
function prototypes in header files; it is obsolete.
- Declare functions of zero arguments
as foo(void) rather than
foo(); foo() means
that the arguments are not checked.
- Use stdarg, not vararg.
- Do not assume that NULL == (void *)0L.
- Do not rely on the ambiguous else rule.
- Every function should return zero if the function succeeds and
a function specific non-zero error code if it fails.
- Macros IN, OUT and INOUT
(expanding to nothing)
must be used
to denote input, output and input-output parameters.
- All exported functions in a module must be prefixed with a unique
identifier derived from the name of the module.
3.3 Other conventions
- The specification of any function exported from a module must
include suitable pre- and postconditions. These pre- and
postconditions
must be checked for in the implementation of the function.
- Also other critical
assertions should be checked using an assert-like
macro or something.
- A module must be fully usable on the basis of header file information
only.
4 Scheme coding policy
4.1 Lexical conventions
4.2 Other conventions
- Write R4RS compliant code if your code should be
runnable outside SCHEMESTATION.
- Write functional code when possible; it is more easy to understand.