Bret Juliano. Introduction What Documentation is Required? – To use a program – To believe a...

13
Bret Juliano

Transcript of Bret Juliano. Introduction What Documentation is Required? – To use a program – To believe a...

Page 1: 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.

Bret Juliano

Page 2: 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.

• 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?

Page 3: 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.

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.

Page 4: 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.

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

Page 5: 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.

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

Page 6: 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.

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

Page 7: 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.

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.

Page 8: 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.

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.

Page 9: 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.

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

Page 10: 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.

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.

Page 11: 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.

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.

Page 12: 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.

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

code.

Page 13: 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.