CSE1301 Computer Programming: Lecture 13 Documentation

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 Example const 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