CS Department
Documentation Standards

Synopsis

The following is a description of expected program documentation. See also the Program Style Guide.

Comments

Comments allow us to write in natural language to clarify the intent of the program. Comment programs internally with clear, coherent statements in concise English, using good grammar, punctuation, and spelling. You might try writing the comments first, then the program to comply with the comments.

What comments should always be in a program?

Header Comments

At the beginning of any file you should have at least:

For each function in the file, you also include:

If the file contains only a single function, this information should be in the header. Otherwise, it should be immediately above each function implementation.

The following templates may be used as a starting point for your documentation.

It is strongly recommended that you use the format for comments shown in these templates. We have also provided sample documentation for a function to calculate averages. This example is based on the first template.

Variable Declaration Comments

In the declaration section, provide a short description of the logical role played by each variable. Organize this section as a legend. For example, in a C++ program you might have:

    double weight;       // The package's weight in kilograms

Comments for Code Sections

Each section that performs a task should be preceded by a comment explaining the purpose of the section and the algorithm being used to carry it out. Individual statements that are complex or non-intuitive should also be preceded by comments (or followed by a comment if it fits on the same line). An end brace after a long block should have a short comment connecting it to its respective beginning brace. You should also include such comments for end braces when you have a number of nested blocks. Here is an example in C++:

    // CALCULATE THE AVERAGE by summing the values and
    // then dividing by the number of values.
    sum = 0;
    for ( i = 0; i <  max; i++ )
    {
        sum = sum + values[i];      // accumulate sum
        // other statements if necessary ...
    } // end of loop calculating sum
    avg = sum / max;

Use blank lines to separate different sections of the program (see the Program Style Guide).

Revision History: September 1993, September 1998, March 2001, April & December 2015 (added C header and Java templates)