<< Ch. 14 – Hatching a Catastrophe
It is not enough to just talk about documentation, the “masters” need to show the kids how to do it!
What Documentation is Required?
To use a program:
- Purpose: what is the main function, the reason of the program?
- Environment: machines, hardware configuration, OS configuration, etc.
- Domain & Range: domain of valid input and range of expected outputs
- Functions Realized and Algorithms used: exactly what does it do?
- Input and Output formats
- Operating Instructions
- Options
- Running Time
- Accuracy and Checking
To believe a program:
On top of the “how to use a program” documentation, you need documentation to convince people that the program is working. This means tests cases.
- Mainline cases that test the program’s chief functions for commonly encountered data
- Barely legitimate cases that probe the edge of the input data domain, ensuring that largest possible values, smallest possible values, and all kinds of valid exceptions work
- Barely illegitimate cases that probe the domain boundary from the other side, ensuring that invalid inputs raise proper diagnostic messages
To modify a program:
- A flow chart or subprogram structure graph
- Complete descriptions of the algorithms used, or else references to such descriptions in the literature
- An explanation of the layout of all files used
- An overview of the pass structure – the sequence in which data or programs are brought from tape/disk – and what is accomplished on each pass
- A discussion of modifications contemplated in the original design, the nature and location of hooks and exits, and discursive discussion of the ideas of the original author about what modifications might be desirable and how one might proceed. His observations on hidden pitfalls are also useful
The Flow-Chart Curse
Flow charts show the decision structure of a program, which is only one aspect of its structure. They show decision structure rather elegantly when the flow chart is on one page, but the overview breaks down when it goes into multiple pages.
Flow charts don’t need to follow the ANSI flow-charting standards. The rules are needed only to give intelligibility to detailed flow charts.
Most of the time, flow charts are done after-the-fact.
Self-Documenting Programs
In practice, the documentation is wholly separate from the actual program. This results in poor documentation and even worse maintenance.
The solution is to incorporate the documentation in the source program (aka self-documenting programs).
An Approach
First, use parts of the program that have to be there anyway to carry as much of the documentation as possibl e.
Second, use space and format as much as possible to improve readability and to show subordination and nesting
Third, insert the necessary prose documentation into th eprogram as paragraphs of comments
Some Techniques
Refer to the book, he gives and example of a piece of self-documenting code with comments and annotates them. Impressive stuff
Why not?
The most serious objection to self-documenting code is the increase in the size of the source code that must be stored (ha!).
Another objection suggests that this kind of program requires more keystrokes. But this is false since you no longer need to maintain the lengthy external docs.