Next: Variable Names Up: Some Notes on Previous: Separate Files

Comments

A well written program uses comment statements heavily. Count on the comment lines to outnumber the lines of actual code.

At the start of each program or subprogram, there should be a comment block that describes exactly what the purpose of the program or subprogram is. There should also be a description how to use it, and of possible limitations and bugs. Put a date in there when the subroutine was first written, and a list of later dates that changes were made. Do not think that years later you will remember that say heat.f is a program to solve the unsteady heat equation in a bar with Dirichlet boundary conditions using an explicit numerical scheme.

When you declare the variables used by your program (see below), add a comment that describes exactly what each variable is. This is equivalent to having a list of notations, and it greatly helps in figuring out what each part of your program does. Also, list special considerations, such as that the variable is later equivalenced to another variable, or is at times undefined.

In particular for subroutines and functions, make sure that you fully describe each argument. Typically, the subroutine will be used as a black box.

Further comments are needed to explain the general purpose of each part of your program. Use blank lines freely to improve readability, by keeping program units visibly separated.

For each individual line of source code, you should ask yourself what information would be needed for a complete stranger to understand its function.

Many programmers add a comment statement to each source line. However, this often leads to such worthless information as `i is set to zero' for a FORTRAN source statement `i=0'. If the comment has no useful information, leave it away. Also, often some information in front of a group of statements is more helpful than a comment for each line. For example, it is more helpful to have a statement to the effect that the next piece of program sums the Taylor series for erf(x) using expression 35.1 in the Mathematical Handbook' than to have the comments `sum is initialized', `tn is initialized', `tn is updated', `sum is incremented', `sum is scaled', and `sum is written to the output file'. Count on the person reading your program to be smart enough to know how a sum is programmed (and what a write statement does).


Next: Variable Names Up: Some Notes on Previous: Separate Files