Every procedure should be documented to show what it does and what its parameters mean. You are expected to provide your own test data for every program as well as demonstrate its accuracy on standard data. We will run your programs on our own test data, which will not generally be made available to you in advance. We encourage students to share test data with each another. 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. Such comments should be written before the rest of the program. Your code should be as clear and simple as possible, but occasionally you may need to resort to a clever trick.