Code Documentation Standards

The following are minimum standards. If you use a process or tool (such as Rational Rose) that provides additional documentation, it may be included.

• The beginning of each source file should contain:
• The name of the file.
• A short description of the purpose of the file.
• The date it was originally written.
• The original author.
• A modification log (when appropriate) that describes:
• When the modifications were made.
• Who made the modifications.
• What modifications were made (fewer than 10 words per change are usually sufficient).
• If you are using a revision control system, the automatic inclusions made by the system are adequate for this purpose.
• Each function prototype should contain the following documentation:
• What the function does.
• The parameters passed in the formal argument list (if there is one parameter and its purpose is obvious [such as const obj & src in obj's copy constructor], it does not need to be documented).
• What the function returns (if anything).
• The following documentation should precede each function body:
• Any sources other than the author (Web URL, fellow student, etc.) that aided in the design of the function (and what aid was provided).
• A modification log (when appropriate) for the function.
• Within each function, documentation should be provided for any code whose purpose is not immediately obvious to someone with your current level of programming knowledge. "Immediately obvious" is all relative; in my early experience, what was immediately obvious in code I wrote myself was totally obscure a year later. This led to a couple of problems: a) I spent too much time re-understanding why I had done something in a certain fashion, and b) I spent too much time answering questions for people that had taken over maintenance of my code. Over time, I've become far more verbose in my style.

Examples:

    Source Module heading

    Source Header

    Method (Function) heading

This page was last updated on 02/28/2007.