CSci 101 Documentation Guidelines

All programs written for CSci 101 (both for homework and lab assignments) are required to follow the guidelines specified in this document. Part of your grade for these assignments will reflect how well you did with your documentation.

There is more to programming than simply writing computer code. We must also write code that is understandable to humans. Someday you may have to go back and look at code that you wrote a long time ago. If you do not pay attention to your documentation, that task will be much more difficult. Someday someone else may have to look at code you wrote before. To prevent that person from bothering you about what you wrote, it is helpful for others to be able to read your code easily. Finally, your TAs and instructors have to read the code you write in order to assign a grade. You will not get full credit for your programming assignments if you do not write good documentation.

For the most part, documentation consists of comments included in the program, but also includes use of meaningful identifier and function names, and consistent and proper use of indentation and spacing that helps convey the structure and meaning of the code.

Comments

Each program should begin with an introductory comment of the following form:

/******************************************************************
 * <filename> - <brief title (one line) of program>
 *
 * Written by:  <your name>
 *              <your login id>
 * Course:      CSci 101
 * Section:     <your section number>
 * Date:        <today's date>
 *
 * Description: <Longer description (may be multiple lines) including
 *              purpose of program, what it does, how it works, etc.>
 *
 *******************************************************************/

Each function should begin with a comment of the following form:

/******************************************************************
 * <function name>
 *
 * PRE:  <list of pre-conditions, usually stated in terms of input arguments>
 * POST: <list of post-conditions, usually stated in terms of output arguments>
 * 
 *******************************************************************/

Pre-conditions are conditions that must hold prior to the invocation of the function.
Post-conditions are those conditions that are true after the function returns.

There should be a comment next to each declaration in the program, unless the identifier sufficiently conveys the intended use of the declaration.
Obscure or complicated sections of code should be preceded by a comment which explains the intent of the code.

Identifiers

Variable names should convey the intended purpose of the variable. For example, found might refer to a variable that contains a Boolean value, which gets set to true when a searched-for item is detected, and is false otherwise. If an identifier consists of more than one English word, capitalize each new word (currentTime). Again, you need to choose good names for your variables and indicate in a comment what the variable is used for.
Function names should be verbs that indicate the action performed by the function, for example initializeArray(). Capitalize each new word in the function name. Functions that return Boolean values should be named with verb phrases that describe the condition that holds when the function returns the value true, for example, isFull(). Methods which provide access to the values stored in private variables should follow the get/set naming convention. For example, if a private variable is named accountBalance, accessor methods should be called getAccountBalance() and setAccountBalance().

Indentation and Spacing

Align all statements that appear at the same level. Use three or four spaces for each nested level of indentation (be consistent).
Align a comment that describes a block of code with the code. Precede the comment with a blank line.
Place the curly braces that delimit the body of a function in column one, and on lines by themselves.
For compound statements, place the opening brace on the line that begins the compound statement and place the closing brace on a line by itself, lined up with the line beginning the compound statement, for example,
```
    if (i == 0) {
        done = true;
        j++;
    }
```

Last modified: Sun Aug 26 14:59:24 EDT 2001 by Diane Kramer
Thanks to Glynis Hamel for preparing the original draft of this document.