692
Appendix F
Program Style, Formatting, and Documentation
Useful programs have very long lifetimes, during which they must be modified and updated.
Good style and documentation are essential if another programmer is to understand and work
with your program.General Guidelines
Style is of benefit only for a human reader of your programs—differences in style make no
difference to the computer. Good style includes the use of meaningful identifiers, comments,
and indentation of control structures, all of which help others to understand and work with
your program. Perhaps the most important aspect of program style is consistency. If the
style within a program is not consistent, it then becomes misleading and confusing.Comments
Comments are extra information included to make a program easier to understand. You
should include a comment anywhere the code is difficult to understand. However, don’t
overcomment. Too many comments in a program can obscure the code and be a source of
distraction.
In our style, there are four basic types of comments: headers, declarations, in-line, and
sidebar.
Header commentsappear at the top of a class, method, or package and should include your
name, the date that the code was written, and its purpose. It is also useful to include sections
describing the input, output, and assumptions that form the basis for the design of the code.
The header comments serve as the reader’s introduction to your program. Here is an ex-
ample:// This method computes the sidereal time for a given date and solar time
//
// Written by: Your Name
//
// Date completed: 4/8/03
//
// Input: java.util.calendar object for the date and solar time
//
// Output: a java.util.calendar object containing the corresponding
// sidereal time
//
// Assumptions: Solar time is specified for a longitude of 0 degrees