Coding Guidelines

1. Code Documentation:

Use meaningful names for variables, constants, and functions. Names should be descriptive, but avoid unnecessarily long identifiers.

Each module should have a set of prologue comments preceding the actual code. The prologue should consist of: name of the module, its purpose (a brief description of the module), a list of input parameters, a list of output parameters, a list of submodules invoked by this module, the author's name, the creation date, the reviewer's name, the date of review, and a maintenance history of the module (for each modification to the module, it should contain the name of the individual making the change, the date of the change, a brief description of the change, the name of the individual reviewing the change (if any), and the date of the review. The following is a sample template.

/****************************************************************************************

Name of Module: <enter name here with "sample" calling sequence>

Purpose: <enter a brief description here>

Inputs: <enter names, types, and descriptions of inputs here>

Outputs: <enter names, types, and descriptions of outputs here>

Submodules: <list submodules invoked by this module here>

Author: <name of author>

Date: <original creation date>

Reviewer: <name of reviewer>

Date: <date of review>

Revision History: <repeat the following for each revision>

Programmer:

Date:

Description of Change:

Reviewer:

Date of Review:

****************************************************************************************/

The code should contain sufficient internal comments to make the code understandable. Comments should provide something extra and not just paraphrase the code. Descriptive comments should:

• Describe blocks of code, rather than commenting every line.
• Use blank lines or indentation so that comments can be readily distinguished from code.
• Be correct: an incorrect or misleading comment is worse than no comment at all.

2. Data Declaration:

All data items and data structures should be declared at the beginning of the module (or block) in which they are used.

Within the declaration statements group similar data types together, e.g., put all integers together, all reals together, etc.

3. Statement Construction:

Construct statements according to the following guidelines:

• Do not put multiple statements on a single line
• Use indentation to show program structure (and use it consistently)
• Avoid the use of complicated conditional tests
• Avoid heavy nesting of loops or conditions
• Use parentheses to clarity logical or arithmetic expressions
• Use spacing (e.g. blank lines) to clarify code
• Use only standard language features (if a standard exists)