The Other FaceThe Other FaceChapter 15Chapter 15

What documentation is What documentation is required?required?

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

1) Purpose1) Purpose►What is the main function, the reason What is the main function, the reason

for the program? ( not int main() )for the program? ( not int main() )

2) Environment2) Environment►On what machines, hardware configurations, On what machines, hardware configurations,

and operating system configurations will it run?and operating system configurations will it run?

Q: “does this work on mac?”Q: “does this work on mac?”A: “does anything work on mac?”A: “does anything work on mac?”

3) Domain and Range3) Domain and Range►What domain of input is valid?What domain of input is valid?►What ranges of output can legitimately What ranges of output can legitimately

appear?appear?

“..it’s voice activated?”“..it’s voice activated?”

4) Functions realized and algorithms 4) Functions realized and algorithms usedused

►What exactly does it do?What exactly does it do?

5) Input-output formats5) Input-output formats►Precise and completePrecise and complete

“…so wait.. what do I type here again?”“…so wait.. what do I type here again?”

6) Operating instructions6) Operating instructions► Including normal and abnormal ending Including normal and abnormal ending

behavior, as seen at the console and behavior, as seen at the console and on the outputs.on the outputs.

“…“…is it supposed to do that?”is it supposed to do that?”

7) Options7) Options►What choices does the user have about What choices does the user have about

functions?functions?► Exactly how are those choices specified?Exactly how are those choices specified?

“…can we do that?”“…can we do that?”

8) Running time8) Running time►How long does it take to do a problem of How long does it take to do a problem of

specified size on a specific configuration?specified size on a specific configuration?

“…“…shouldn’t it be done by now? ..I think I shouldn’t it be done by now? ..I think I broke it…”broke it…”

9) Accuracy and checking9) Accuracy and checking► How precise are the answers expected to be?How precise are the answers expected to be?►What means of checking accuracy are What means of checking accuracy are

incorporated?incorporated?

““that’s what it says.. but it doesn’t look right”that’s what it says.. but it doesn’t look right”

Test CasesTest Cases1.1. Test that the program’s main Test that the program’s main

functions with commonly functions with commonly encountered dataencountered data

2.2. Test barely legitimate input dataTest barely legitimate input data3.3. Test barely illegitimate input dataTest barely illegitimate input data

Flow ChartFlow Chart► Is the flowchart Is the flowchart

outdated?outdated?

Flow Chart (Continued)Flow Chart (Continued)►Has OOP and the lack of GOTO Has OOP and the lack of GOTO

statements in modern programming statements in modern programming helped outdate the flow chart?helped outdate the flow chart?

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

And the most useful And the most useful documentation techniques documentation techniques

mentioned are…mentioned are…► Use a separate job name for each run, and maintain a Use a separate job name for each run, and maintain a

run log showing what was tried, when, and the results.run log showing what was tried, when, and the results.► Use a program name that is mnemonic but also Use a program name that is mnemonic but also

contains version identifiers (ie. AIM 5.9.3828)contains version identifiers (ie. AIM 5.9.3828)► Show relationship to book algorithms (ie. “This is a Show relationship to book algorithms (ie. “This is a

modified version of Dijkstra’s shortest path algorithm modified version of Dijkstra’s shortest path algorithm for multiple users”)for multiple users”)

► Label sections of code (ie. Includes, initializations, etc.)Label sections of code (ie. Includes, initializations, etc.)► Use indenting (format it properly)Use indenting (format it properly)► If the code’s printed, possibly add control flow arrows If the code’s printed, possibly add control flow arrows

by hand (from one function to another)by hand (from one function to another)► Use line comments only for things that are not obviousUse line comments only for things that are not obvious► Group things together whenever possibleGroup things together whenever possible

Das EndeDas Ende►Fraggen?Fraggen?