Guidelines for Documenting & Structuring Programs
Here are some general guidelines for documenting and structuring your programs. With regards to documentation, note the pervasive use of the word briefly. Documentation will be assessed by
quality; not by volume. The primary goal is to make your programs easier for you to write and easier for an outsider to read, use, and modify. Note that these guidelines are very generic (i.e., they are not specific to Java or C++) and are based on guidelines that have been developed for programs in COMP 14 & 114.
For each
program:
For each
class:Briefly describe
the function of, and operations allowed on class types. Provide meaningful pre- and post-conditions on each operation. Give examples of how to use each class type.
For each non-trivial
procedure and function:Briefly document the
purpose of each procedure and function as well as the function of all parameters. If applicable, describe the algorithm or data structure(s) used in the procedure.
Each procedure and function should have as meaningful a
pre- and post-condition as is possible to state.For each non-trivial
loop:Each loop should have as meaningful an
invariant as is possible to state as well as a brief English description of what the loop is doing.
Some general guidelines of what not to do
:Don't imbed "
magic numbers" in your program. Declare them as constants. (For our purposes, a magic number is defined as a number whose role in the program is not immediately obvious in the statement in which it appears.)
Don't be
long winded. In particular, don't assert or comment on properties that are guaranteed by the semantics of the language (unless doing so is desirable for emphasis).
Don't try to impress the TA or the Professor with overly clever,
cryptic, or optimized code.