The Other Face Chapter 15

What documentation is required? ► Different levels of documentation are required for the casual user of a program, for the user who must depend upon a program, and for the user who must adapt the program for changes in circumstance or purpose.

1) Purpose ► What is the main function, the reason for the program? ( not int main() )

2) Environment ► On what machines, hardware configurations, and operating system configurations will it run? Q: “does this work on mac?” A: “does anything work on mac?”

3) Domain and Range ► What domain of input is valid? ► What ranges of output can legitimately appear? “..it’s voice activated?”

4) Functions realized and algorithms used ► What exactly does it do?

5) Input-output formats ► Precise and complete “…so wait.. what do I type here again?”

6) Operating instructions ► Including normal and abnormal ending behavior, as seen at the console and on the outputs. “…is it supposed to do that?”

7) Options ► What choices does the user have about functions? ► Exactly how are those choices specified? “…can we do that?”

8) Running time ► How long does it take to do a problem of specified size on a specific configuration? “…shouldn’t it be done by now?..I think I broke it…”

9) Accuracy and checking ► How precise are the answers expected to be? ► What means of checking accuracy are incorporated? “that’s what it says.. but it doesn’t look right”

Test Cases 1. Test that the program’s main functions with commonly encountered data 2. Test barely legitimate input data 3. Test barely illegitimate input data

Flow Chart ► Is the flowchart outdated?

Flow Chart (Continued) ► Has OOP and the lack of GOTO statements in modern programming helped outdate the flow chart?

Self Documenting ► i.e. Comment the code to death

And the most useful documentation techniques mentioned are… ► Use a separate job name for each run, and maintain a run log showing what was tried, when, and the results. ► Use a program name that is mnemonic but also contains version identifiers (ie. AIM ) ► Show relationship to book algorithms (ie. “This is a modified version of Dijkstra’s shortest path algorithm for multiple users”) ► Label sections of code (ie. Includes, initializations, etc.) ► Use indenting (format it properly) ► If the code’s printed, possibly add control flow arrows by hand (from one function to another) ► Use line comments only for things that are not obvious ► Group things together whenever possible

Das Ende ► Fraggen?