MCS 220 Documentation Rules
There are five requirements for documentation:
The first and most important documentation rule is that all identifier names (class names,
method names, and variable names) must be descriptive of what the identifier is used for. In
particular, no one character variable names are ever acceptable, short cryptic names or
abbreviations should be avoided, and over-used generic names (such as “count” or “number”)
which do not tell how the variable differs from other similar variables should be avoided.
The second rule is that internal comments and white space should be used consistently. White
space refers to blank lines between lines of code as well as to indentation of code. In general,
code should be single spaced with blank lines being inserted to show endings of blocks of code.
Blank lines should also separate class and method declarations, and the number of blank lines
used for each separation should be consistent throughout the program. Indentation should be
used to show that some lines of code belong to a larger structure of code. The amount and style
of indentation should be consistent throughout the program. Internal comments do not have to
be full sentences. They should occur every five to ten lines of code, especially before important
blocks of code, to aid the reading and understanding of the code.
Magic numbers refer to numerical constants used within a computer program. The trouble with
magic numbers is that they are not self-documenting; they do not tell the reader why they are
there. They make understanding and maintaining of the code difficult. Magic numbers of 0
and 1 may be used throughout the program. Magic numbers may appear in any declaration
statement or in statements where they specify input/output formatting. Otherwise, magic
numbers should not appear.
Each method should have a method prologue written in full sentences with proper punctuation.
Prologues need not be long and can be as short as one or two sentences. They should tell the job
that is being performed by the method and tell how the method communicates with the rest of the
program. Each parameter appearing in the parameter list of a method should be referred to in
the prologue. If the method changes the value of a variable which is not local to the method, the
prologue should mention that also. Someone wanting to use the method should be able to read
the prologue of the method and know how to use the method without having to read any of the
code of the method.
Finally, each program needs a program prologue. The prologue should begin with the author’s
name, the programming assignment’s name or number, the instructor’s name, the author’s e-mail
address, and the program’s completion date. Then the prologue needs to have the following
three sections each written in full sentences:
• PURPOSE: This section should be directed to a non-programmer. It needs to describe
the job being performed by the program in a non-technical way or, if the program is just a
technical exercise, then in as non-technical terms as possible.
• DATA: This section of the prologue is directed to the operator of the program. If the
program requires that the user of the program prepare a data set before the program is run,
then this section must completely describe that data set so that the user can prepare the
data set. It should include a statement telling what each record in the data set represents,
give the format of each data record, specify the type and range of information appearing
in each data field, and tell anything the user would be required to know about the number
or order that the records must appear. There should be enough information in the data
description so that if the user follows the direction, the program will give the correct
• MAINTENANCE: This section is directed to a programmer who is about to read your
program code. As such, it should give the reader a head-start toward understanding your
program. It should describe each of the classes written as part of your program, mention
the use of each of the important variables in the program, and give an outline showing the
main logical structure of the program. Pseudocode or other outline method would be
suitable for this and may not need to appear as complete sentences.