next up previous
Next: The Evolution of Documentation Up: Documentation Previous: Why Document A Program?

Levels of Documentation


A code can be rated according to where it falls on this sequential list:

0. Layout
0-a. Consistency
0-b. Logical Block Structure (Few or No Branches)
0-c. Indentation to Show Logical Structure
0-d. Blank Lines and Spaces for Readability
0-e. Statements Grouped Semantically
1. Descriptive Variable and Routine Names
2. Comments throughout the Code
3. Routine Headers with
3-a. Purpose
3-b. Input/Output Variable Descriptions
3-c. Internal Variable Descriptions
3-d. Methods Employed
4. Hardcopy Documentation
4-a. Code Listing
4-b. Code Manual
4-c. User's Manual
4-d. Method Discussion
5. Hypertext Documentation
5-a. Code Listing
5-b. Code Manual
5-c. User's Manual
5-d. Method Discussion
5-e. External Links
6. Literate Programming:
Source Code and Documentation are Generated from the Same File

Articles on methods constitute supporting, but ancillary, documentation of a code. They should be included in the references of the hardcopy version and the external links of the hypertext version.


next up previous
Next: The Evolution of Documentation Up: Documentation Previous: Why Document A Program?
Michael L. Hall