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.
- Programs must begin with a comment block which identifies the
Even though I assigned the lab work, you must assume that I don't
know anything about your program.
- Author or authors.
- Purpose of the program.
- Brief, high-level description of what the program does.
- Each class must begin with a comment block which identifies:
This comment block must stand out so that it is easy to locate the class
within the program file.
- Class name.
- Brief description of the class' purpose.
- 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.
- 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.
- 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.
- If you borrow code snippets from the lab programs, cut all comments
which are irrelevant to your program.
- Notice how lab code is indented carefully and consistently to improve
readability. Indent your own code in a similarly careful and consistent
Thomas P. Kelliher
Tue Oct 29 14:02:39 EST 2002