CSE1301 Computer Programming:

Lecture 13Documentation

Topics

• System documentation – Internal Documentation (in-line comments) – Program Documentation (external)

• User documentation

• Reading: The Style, Chapter 1, 2, 4 and 7.

Brookshear 6.5 (4/e and 5/e), 6.6 (6/e).

Documentation

• Is usually neglected or poorly done

• It is vital to the usability of software

• It is the difference between a program and a marketable product

• Documentation may occupy up to 30% or more of the development time

Why is documentation needed?

• Software is no use unless people can use and maintain it.

• Two purposes: – explain software features, describe how to use

them: user documentation.– describe software so system can be maintained

later in life cycle: system documentation (including internal documentation).

System documentation

• Historically: final source pograms + sketchy explanations written after software was developed. This is no longer acceptable.

• Begins with original system specifications, continues through the software's life cycle.

• The development of system documentation is an on-going process: – must be updated as specs or design changes.– made easier by CASE tools.

Internal documentation

• General Philosophy

Write comments where they will provide additional and necessary information for people reading your code.

• Note - if you had trouble writing the code, someone else will have trouble reading it!

Strategic comments

• Describe how a function or type behaves

• Explain the interface of a program

• Typically appear in a block

Tactical comments

• Describe the use of a variable or a complicated section of code

• Explain implementation details

• Typically appear on a single line

Non-Trivial Comments: Bad example

Restating what code says doesn't help reader.

int age = 7; /* declare age variable */char name[20]; /* declare string var for name *//* * Read in a name and age and then check if its * end of input or if age is 7 and if neither * is the case then print out the name and age */while ((scanf("%s %d", name, &age)!=EOF) && (age != 7)){ printf("%s %d\n", name, age);}

Non-Trivial Comments:Good Example

int age = 7; char name[MAXNAMELEN+1];

/* * Read in and print out name and age pairs, * until a 7 year old is found. */

while ((scanf("%s %d", name, &age) != EOF) && (age != 7)){ printf("%s %d\n", name, age);}

Comment Blocks

• When describing a block of code, use a comment block which is easily distinguishable from the code around it.

Comment Blocks: Bad Example

/* This is a multi-line

comment. It describes the function which follows it. */

int myfunc()

{

...

}

Comment Blocks: Good Example

/*

* This is a multi-line comment. It describes the

* function which follows it.

* Note the layout of the *'s and the beginning

* and end of the comment.

*/

int myfunc()

{

...

}

Comment Blocks: Good Example 2

/*

** This is a multi-line comment. It describes the

** function which follows it.

** Note the layout of the *'s and the beginning

** and end of the comment.

*/

int myfunc()

{

...

}

Use of language

• Use plain English and full sentences in the text of a block comment.

Use of language: Bad example

/*

* this is a multi-line comment, obviously

* spans number of lines

* not conventional sentence form where

* does one

* sentence end and another start

*/

Use of language: Good example

/*

* This is a multi-line comment which obviously

* spans a number of lines. It is in conventional

* sentence form.

*/

Single Line Comments

• Short single lines of code may be given a comment that starts and ends on that same line.

Single Line Comments: Bad Example (over -

commented)

/*

* The next line declares a variable which holds

* the number of failures in the course

*/

int failures;

int students; /* How many students enrolled */

/* Array of course code strings */

char ** courseCodes;

Single Line Comments: Good Example

int failures; /* Number of failures */

int students; /* Number of students */

char** coursecodes; /* Array of course codes */

Note the alignment.

Comment Maintenance

• Ensure that comments and code are maintained together

• Exampleconst int numSides = 3; /* a triangle */

Later becomes:const int numSides = 4; /* a triangle */

Use of abbreviations

• Do not use abbreviations in comments unless they are clearly defined for the project.

• Bad Example/* Calc dist b/w pts */

dist = sqrt(sqr(ax - bx) + sqr(ay - by));

• Good Example/* Calculate the distance between points a and b. */

dist = sqrt(sqr(ax - bx) + sqr(ay - by));

Headings for different modules

• If comments are to be divided into sections, each section of field heading must be in upper-case.

Headings for different modules: Bad Example

/*

* -------------------------------------

* Name: findMin

* Description:

* ------------

* This code will minimise a user

* specified function

* -------------------------------------

*/

Headings for different modules: Good Example

/*

* -------------------------------------

* NAME:

* findMin

*

* DESCRIPTION:

* This code will minimise a user

* specified function.

* -------------------------------------

*/

Coding Standards

• (See “The Style”)

• Layout of code

• Consistent indenting (use of tabs)

• Visual separation

• Bracing style and block indentation

• Meaningful (standard) names

• Abbreviations

Other Internal Documentation

• Legal notices

• Revision history

User documentation

• Explains how to use the program

• Assumes nothing about user

• Explains how to "drive" it

• States what assumptions are made

• Specifies likely error conditions and known bugs

• Estimates space/time efficiency

• Outlines theoretical background

User documentation example

• See StudentMarksUserDoc (Document 1) in lecture notes

Program documentation

• Describes the specifications by which the system was verified

• Explains how to maintain and/or modify the program

• Assumes some understanding on the part of the reader

• Describes the purpose of all non-trivial variables and data structures

Program documentation (cont.)

• Gives an overview of the algorithm (including flow-diagrams, structure charts)

• States conventions/standards used

• Lists entire source code

• Gives example results

• Explains the purpose of each module/subroutine individually

Program documentation (cont.)

• Highlights non-standard language usage (portability constraints)

• Suggests possible improvements or extensions

Program documentation example

• See StudentMarksProgramDoc (Document 2) in lecture notes

Summary

• Documentation is important! You should– Include comments in your programs – Follow the "rules" for comments and general

"style"

• External documentation includes: – Program documentation – User documentation