Documentation standards

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 increases clarity.  Writing in grammatically correct sentences with correctly spelled words increases readability.

Internal documentation

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 the program.

External documentation

External documentation should include descriptions of the following:

Note:  Your name should be inside each file that you write.  Be careful to cite any sources from which you derived your work.

Dan Hirschberg
Computer Science Department
University of California, Irvine, CA 92697-3435
dan (at)
Last modified: Mar 22, 1999