Every program should have external documentation telling how to use the program and what its limitations are. It should also have internal documentation that describes data structures and algorithms. Every procedure should be documented to show what it does and what its parameters mean. You are expected to generate your own test data for every program as well as demonstrate its accuracy on standard data. However, efficiency should never be pursued at the expense of clarity.
Internal documentation consists of the comments included in the program.
Procedure-head comments describe the effects of the procedure and assumptions about its inputs and outputs. The procedure name should convey as much of this information as possible. Names of variables, types, constants, and field selectors should also be as meaningful as possible, with a comment next to the declaration to fill in extra information. Comments should be written before the rest of the program. The first kind of documentation includes details of how to call the program, its options, formats of data, limitations, bugs, and special features.