Next: The Evolution of Documentation
Up: Documentation
Previous: Why Document A Program?
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: The Evolution of Documentation
Up: Documentation
Previous: Why Document A Program?
Michael L. Hall