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. Purpose 2. Environment 3. Domain and Range 4. Functions realized and algorithms used 5. Input-Output formats 6. Operating instructions 7. Options 8. Running time 9. 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.