Documentation serves as an essential interface between programmers
working together, and as the main interface between the final product
and the naive user.
Since documentation is designed to communicate,
it should be clear and unambiguous.
Documentation should be coherent.
Breaking the documentation up into
distinct sections which describe different aspects of the program
Writing in grammatically correct sentences with
correctly spelled words increases readability.
Internal documentation should be concise.
Variable names should be defined;
arbitrary or "magic" numbers should be explained;
and sections of code should be described.
Descriptive variable names are
necessary as an addition to both the documentation and readability of
External documentation should include descriptions of the following:
- How to use the final product.
- The type of input you expect and the
type of output you will generate.
- The type of errors handled and the action
taken on each type of error.
- All special features which you implemented
which were not specified for the lab.
- Any design choices which you made and reasons for these choices.
- Any special files needed to run the program.
Note: Your name should be inside each file that
Be careful to cite any sources from which you derived your work.
Computer Science Department
University of California, Irvine, CA 92697-3435
dan (at) ics.uci.edu
Last modified: Mar 22, 1999