Bret Juliano

• Introduction• What Documentation is Required?

– To use a program– To believe a program– To modify a program

• The Flow-Chart Curse• Self-Documenting Programs

– An approach– Some techniques– Why not?

• Questions?

A computer program is a message from a man to a machine. The syntax and definitions exist solely to make the instructions clear to the machine.

To use a program To believe a program To modify a program

1. Purpose2. Environment3. Domain and Range4. Functions realized and algorithms used5. Input-Output formats6. Operating instructions7. Options8. Running time9. Accuracy and checking

Every copy of a program shipped should include small test cases used for reassuring the user has a faithful program. Microsoft Genuine Advantage

Necessary components:1. A flow chart or structured graph.2. Complete descriptions of algorithms used.3. An explanation of the layout of files.4. An overview of pass structure and what is

accomplished each pass.5. A discussion of modifications from the original

design.

Many programs don’t need a flowchart, let alone one that is over 1 page.

The more you add, the more confusing it gets.

Experienced programmers don’t use flow charts.

Program documentation is generally poor and the maintenance is worse. An approach Some techniques Why not?

Use the parts of the program that have to be there anyway. Labels, declarations, etc

Use space and format to improve readability

When necessary add paragraphs of comments with single line comments.

Use a separate name for each run through. Declare all variables. Mark the initialization by a label. Use indenting to show structure. If it’s not obvious, explain it.

The drawbacks: Increased size of the source code. Flow charts are hard to implement into source

code.