Programming Standards
C is a low level language and, like all low level languages (such as assemblers), must be thoroughly documented so that it can be understood (either by by others, or by the author in years to come), and maintained. The documentation standards for all our C programs are:
- Every statement (including variable definitions) must be commented
- Every routine must start with a block of documentation that explains what it does, and identifies any requirements or constraints. If the routine implements an unobvious solution then the reason for choosing it should be clearly stated (to ensure that no future programmer will gratuitously assume it is wrong, and replace it with more obvious code that has a non-obvious flaw).
- Every source module should start with a block of meaningful documentation (and not just some standard copyright notice).
- Every change to a module must be described in a detailed change log that records both the what and the why of any change.
Neatness ensures clarity, so ...
- Statement-level documentation should start in column 41 (where possible), and end in column 79
- Routine- and module-level documention blocks should be enclosed with boundaries in columns 1 and 79
- Sub-ordinate code should be indented 2 columns, while the enclosing {} brackets should be on lines of their own, indented by 1
Additionally ...
- All modules should compile with no errors and no warnings
- The code for a single module should be of such a length that it can be viewed it total on a screen (so the logic is visible without scrolling)
- There are NO jumps to labels [ie no goto statements]
- Every routine has a single entry point and a single exit point (to facilitate debugging and tracing). Additionally, every routine starts with the macro 'rtstart' and ends with 'rtend'.
- All programs are written to use a standard suite of service routines that faciliate automatic detection of memory overflow, dynamic tracing, dynamic memory monitoring, error logging and, in extremis, a formatted core dump.
An example of these standards can be seen in this code snippet.