Program Documentation Standards

Tom Kelliher, CS 116

Oct. 30, 2002

Beginning with Lab 6, lab and post lab programs you turn in must follow these documentation standards. Obviously, most of these are already done for you with the lab programs. You will need to make sure your post lab programs follow these standards.

1. Programs must begin with a comment block which identifies the following:
   1. Author or authors.
   2. Date.
   3. Purpose of the program.
   4. Brief, high-level description of what the program does.
   Even though I assigned the lab work, you must assume that I don't know anything about your program.

2. Each class must begin with a comment block which identifies:
   1. Class name.
   2. Brief description of the class' purpose.
   This comment block must stand out so that it is easy to locate the class within the program file.

3. Each method must begin with a comment block which briefly describes the method's role within the class. This comment block must stand out so that it is easy to locate the method within the program file.

4. Variable, object and class names must be descriptive. If you must use a non-descriptive name for a variable or object, you must describe the purpose of the variable or object at the point of declaration.

5. When using one of the BlueJ class templates as a skeleton when starting to write your program, cut all methods you aren't using and cut all the comments included with the skeleton. Such methods and comments, if left in your program, are confusing.

6. If you borrow code snippets from the lab programs, cut all comments which are irrelevant to your program.

7. Notice how lab code is indented carefully and consistently to improve readability. Indent your own code in a similarly careful and consistent manner.