Code Documentation

Proper documentation  and comments in the application code itself are essential. As an absolute minimum of documentation in the code, each module must contain the elements below:

• Each code module or file must start with a header comment block that at least contains the required entries defined in Table .
• Any routine or function within a code module must contain a routine comment block immediately after the routine declaration statement. This block must include the required routine entries defined in Table .
• All external or global variables (e.g. COMMON's) must be identified in the module comment block.
• All formal variables in routines or functions must be declared in separate lines with comments indicating their usages and if they are used for input, output or both.
• Each major section of the code must be preceded by a comment describing what the section does.

Usage of meaningful names of variables and functions is recommended to improve readability of the code. Although the exact amount of comments compared to the code will depend on the actual module, a general guideline is that approximately 30% of a module should be comments.