Small font Medium font Larger font Largest font

See Also

CS Student Documentation

CS Faculty Documentation

Computer Science Forms

Site Map

Accessibility Statement

C++ Program Documentation

Left bracket

Guidelines Right bracket

Fall, 1999

Contents

* Why is program documentation important?

* When should program documentation be done?
* What information should be in the program documentation?
* How should program documentation be done?
* an example for CS 202 students
* Additional documentation guidelines
o Keep functions simple!
o Whitespace
o identifiers
o Include files
o Spelling and grammar
o Statement formats
* Documenting user-defined classes
o Header files
o Implementation files
o Main program file

Why is program documentation important?

1) The main purpose of program documentation is to describe the design of your program. The
documentation also provides the framework in which to place the code. as coding progresses, the
code is inserted into the framework already created by the program documentation.

2) Documentation is important to tell other programmers what the program does and how it
works. In the "real world" and in some classes here at BGSU, programmers often work in teams
to develop code. Documentation helps others on the team to understand your work.

3) Maintenance and debugging are needed sooner or later for most programs and these are
frequently done by someone other than the original programmer. Documentation can help the
programmer who is making the modifications understand your code.
4) Documenting your program during development helps you to maintain your sanity.

When should program documentation be done?

When designing your program, you must spend time thinking about how to structure your
program, what modules are needed, and the algorithms and processes you will use in the
modules. You must think about what sort of data structures and objects (e.g., arrays, files or
linked lists) are needed. This thinking must be done before you start coding, or you will find
yourself wasting time writing useless code that is full of errors. It is very important to record this
creative process so that the programmers that follow you do not duplicate work that you have
already done.

Before writing the code, you should write the documentation to describe the design of each
component of your program. Writing documentation for the modules before writing the code helps
you define exactly what each module should do and how it will interact with other modules.
Focusing on the design and the steps needed to solve the problem can help prevent errors in the
completed program.

What information should be in the program documentation?

For an individual module, it is important to record (1) who has written the module, (2) when the
module was written or modified, (3) why the module was written or modified, (4) how the module
interacts with other modules, (5) what special algorithms were used, if any, and (6) acknowledge
outside sources for ideas and algorithms. For data structures, it is important to record (1) what
data structure is used, (2) why a particular structure was used, (3) what data is contained in the
structure, and (4) how the data structure is implemented.

How should program documentation be done?

The following sections contain guidelines for documentation that should appear in a C++ program
file containing a main program and some functions. Documentation or comment lines begin with a
double slash ( // ) and all text to the end of the line is considered a comment. Documentation
should appear
• before the main program (program header)
• before each function (function header)
• before or next to lines of code within a function (line comments)

To help you get started, fill-in-the-blank framework files can be found on bgunix in
/home/cs/documentation.

An example for CS 202 students

Here is an example of a typical programming assignment in CS 202.

CS 202
Lab Assignment 3
Due: 5 pm, October 10

A small university needs help keeping track of enrollment in each of their ten courses. They
have asked you to write a program to help with this task. The first thing that they want is a list of
the enrollment data in order by id number. Write a program that will read in the data, sort it by the
id number and print the sorted list. They would also like to see the total enrollment in all courses.

Input: The user should be prompted for the id number and enrollment in each course.
 Method: Your program should contain 2 parallel arrays to contain the data. Use separate
functions to read in, sort and print the data in the arrays. You should use the bubble sort to sort
the data.

Output: Should be neatly labeled and easy to read. It should include the id number of each
course and the enrollment in that course. Print the output in table form.

A sample solution is presented below. The comments in this solution are representative of the
type of documentation that you should put in your programming assignments. The code has also
been entered in a style which has been effective for students learning the C++ language.

As you are reading through the example, please note the following points (referred to using these
numbers).

1. Function prototypes require that only the data types of the arguments be given. However, by
including parameter names, your code becomes easier to read and self-documenting by stating
what each of the parameters are.
2. There are many styles for the braces in a C++ program. In this example, we have placed
them on a separate line with matching braces at the same indentation level. Studies have shown
that this is easier for beginning programmers.
3. Pseudocode is used to describe the method of this function.
4. Statements that take more than one line to enter are usually indented after the first line.
5. The braces in this statement are optional because there is only one statement in the body of
the loop. However, it is good programming practice to always include the braces. Making changes
to the program later is easier, because the next programmer doesn't have to check if the braces
need to be inserted.
6. Some functions are generic and can be reused in similar circumstances. For this reason,
more generic names are used for the parameters.
7. This section of documentation represents a typical execution of the program. It is helpful in
understanding what the program is expected to do.

// FILE: enroll.cpp
// TITLE: Course Enrollments
// SUBMITTED BY: Ima Student
// All code is my own except where credited to others.
// FOR COURSE: CS 202
// DUE DATE: March 30, 1999
//
// PURPOSE:
// This program will keep track of enrollments in courses at a small
// university. It will read, from the user, the course id number and
// enrollment for each course offered. The data will then be sorted
// from smallest to largest id number. The sorted list will then be
// printed along with the total enrollments for all courses.
//
// OVERALL METHOD:
// The list of general tasks is:
// 1. Input course data from the user and store in parallel one-
// dimensional arrays.
// 2. Sort the parallel arrays by id number. A bubble sort will
// be used.
// 3. Print sorted course data stored in arrays.
// 4. Print total enrollment at university.
//
// FUNCTIONS:
//
// getCourseData
// will read data from the user into arrays and, upon exit,
// return the total enrollment for all courses
//
// bubbleSort
// will sort the arrays of id numbers and enrollments from
// smallest to largest id numbers
//
// printCourseData
// will print the data contained in the arrays and, after
// that, the total enrollment
//
// swap
// is called by bubbleSort to exchange two array values
//
// INCLUDED FILES:
// iostream.h
// iomanip.h
//
// DATA FILES:
// none

#include <iostream.h>
#include <iomanip.h>

int getCourseData( int nCourses, int courseids[], int enrollments[] ); ** note 1 **

void printCourseData( int total, int nCourses, int courseids[], int enrollments[] );
void bubbleSort( int n, int keys[], int values[] );
void swap( int & item1, int & item2 );

int main( )
{ ** note 2 **
const int nCourses = 3; // Program inefficient if nCourses is large!
int courseids[ nCourses ], enrollments[ nCourses ];
int total = getCourseData( nCourses, courseids, enrollments );
bubbleSort( nCourses, courseids, enrollments );
printCourseData( total, nCourses, courseids, enrollments );
return 0; // Error level of 0 means normal termination
} ** note 2 **

// name OF FUNCTION: getCourseData

// CREDIT:
// PURPOSE:
// The function will read, from the user, the course id and the
// enrollment in the course. These values will be stored in a set of
// parallel arrays named "ids" and "totals". The function will return
// the total enrollment.
//
// PARAMETERS:
// name type value/reference description
// ---------------------------------------------------------------------
// n int value number of values in the array
// ids[] int reference the array of id numbers
// totals[] int reference the array of enrollment totals
// for each course
//
// RETURN VALUE:
// name type description
// ---------------------------------------------------------------------
// grandtotal int the overall total enrollment for the university
//
// CALLS TO: none
//
// CALLED FROM: main
//
// METHOD: The following is pseudocode describing how the function works.
// 1. Initialize the grand total to zero. ** note 3 **
// 2. Prompt user for data expected.
// 3. Loop and execute n times.
// Use loop counter as subscript of arrays
// 3.1 Prompt user for specific course data.
// 3.2 Read in id.
// 3.3 Read in enrollment.
// 3.4 Add to enrollment to the grand total.
// 4. Return the grand total.

int getCourseData( int n, int ids[], int totals[] )

{
int grandTotal = 0;
cout << endl ** note 4 **
<< "For each of " << n << " courses," << endl
<< " enter the course id and the number of students in that course."
<< endl
<< " Enter these two values on one line, separated by a space."
<< endl
<< endl;

for ( int i = 0; i < n; i++ )

{
cout << "Course " << i + 1 << " -- id and number of students: ";
cin >> ids[i] >> totals[i];
grandTotal += totals[i];
}
return grandTotal;
}

// name OF FUNCTION: printCourseData

// CREDIT:
// PURPOSE:
// The function will loop through parallel data arrays named "ids" and
// "totals", and will print out the course id and enrollment for each
// course. Finally, it will print out the total enrollment. Formatting
// is applied to make the output readable by humans.
//
// PARAMETERS:
// name type value/reference description
// ---------------------------------------------------------------------
// gTot int value the overall total enrollment
// n int value number of values in the array
// ids[] int reference the array of id numbers
// totals[] int reference the array of enrollment totals
// for each course
//
// RETURN VALUE: none
//
// CALLS TO: none
//
// CALLED FROM: main
//
// METHOD: The following is pseudocode describing how the function works.
// 1. Print titles for the columns of data.
// 2. Print a separator.
// 3. Loop and execute n times. Use the loop counter to index the arrays.
// 3.1 Print the course id.
// 3.2 Print the enrollment in that course.
// 4. Print a separator.
// 5. Print the enrollment for the entire university.

void printCourseData( int gTot, int n, int ids[], int totals[] )

{
cout << endl
<< setw(10) << "Class id"
<< setw(12) << "Enrollment" << endl
<< "----------------------" << endl;
for ( int i = 0; i < n; i++ )
{ ** note 5 **
cout << setw(10) << ids[i]
<< setw(12) << totals[i] << endl;
} ** note 5 **
cout << "----------------------" << endl
<< setw(10) << "Total" << setw(12) << gTot << endl;
}

// name OF FUNCTION: bubbleSort

// CREDIT: Adapted from Robert Sedgewick, ALGORITHMS (1992), page 101.
// PURPOSE:
// This generic function will sort parallel data arrays, one containing
// keys, the other containing values associated 1-to-1 with those keys.
//
// PARAMETERS:
// name type value/reference description
// ---------------------------------------------------------------------
// n int value number of values in the array
// keys[] int reference the array of keys
// values[] int reference the array of values for each course
//
// RETURN VALUE: none
//
// CALLS TO: swap
//
// CALLED FROM: main
//
// METHOD: The following is pseudocode describing how the function works
// 1. Do the following n-1 times.
// 1.1 Point to the first element of the array containing keys.
// 1.2 Do the following n-1 times.
// 1.2.1 Compare the element pointed to with the next element.
// 1.2.2 If the compared elements are in the wrong order ...
// 1.2.2.1 Swap the keys.
// 1.2.2.2 Swap the values associated with those keys.
// 1.2.3 Point to the next element.
//
// NOTE:
// This method is extremely inefficient except for small arrays.

void bubbleSort( int n, int keys[], int values[] ) ** note 6 **

{
int last, next;
for ( int i = 1; i < n; i++ )
{
last = n - i;
for ( int j = 0; j < last; j++ )
{
next = j + 1;
if ( keys[j] > keys[next] )
{
swap( keys[j], keys[next] );
swap( values[j], values[next] );
}
}
}
}

// name OF FUNCTION: swap

// CREDIT:
// PURPOSE:
// This utility function exchanges the values of its two parameters.
//
// PARAMETERS:
// name type value/reference description
// ---------------------------------------------------------------------
// item1 int reference item to be swapped with item2
// item2 int reference item to be swapped with item1
//
// RETURN VALUE: none
//
// CALLS TO: none
//
// CALLED FROM: bubbleSort
//
// METHOD: The following is pseudocode describing how the function works.
// 1. Save a reference to item1's content.
// 2. Store in item1 a reference to item2's content.
// 3. Using the saved reference, store in item2 a reference to
// item1's original content.

void swap( int & item1, int & item2 )

{
int temp = item1;
item1 = item2;
item2 = temp;
}

// EXAMPLE INPUT AND OUTPUT ** note 7 **

 //
// For each of 3 courses,
// enter the course id and the number of students in that course.
// Enter these two values on one line, separated by a space.
//
// Course 1 -- id and number of students: 8402 21
// Course 2 -- id and number of students: 3589 35
// Course 3 -- id and number of students: 4521 59
//
// Class id Enrollment
// ----------------------
// 3589 35
// 4521 59
// 8402 21
// ----------------------
// Total 115

Additional documentation guidelines

Keep functions simple!

Functions of 5 to 25 lines, not counting comments, are recommended. In practice, this means that
if you can't see the entire block on the terminal screen at one time, it probably needs to be broken
into components which do fit on the screen. C++ main() functions often tend to be too long. It is
recommended that they not exceed 25 lines or 20% of the total program length, whichever is less.
Whitespace

The format of the source code is important in the readability of a program. The term "format"
refers to both horizontal and vertical white space. In higher level languages, blank lines can be
used for vertical spacing and, for horizontal spacing, blocks of code can be indented.
identifiers

The identifiers (function, variable and constant names) which are used also affect the readability
of a program. Make identifiers more self-documenting by carefully and creatively choosing names
which are close to English but long enough to be meaningful in terms of the task being
performed. For example, testScores is a much better name for an array than intArray, and
computeAverage is a better name for a function than doCalculations.
Include files

All include files used in a program file should be put at the beginning of the file. Put system-
defined include files (<…>) before user-defined include files ("…"), as in the following short
example:

#include <iomanip.h>
#include <iostream.h>
#include "date1.h"
#include "myobject.h"

Spelling and grammar

Correct spelling and good grammar should be used throughout the comments. Be prepared to be
evaluated both as a programmer and as a technical writer.
Statement formats

The following table shows how to format and indent various C++ features.
C++ function
void main(int argc, char *argv[])
{
// Body of function indented within { }
}

if statement

if (condition)
// one statement indented
else
// one statement indented

if statement with blocks

if (condition)
{ // multiple
// statements
// indented
}
else
{ // multiple
// statements
// indented
}

if statement with else if

if (condition1)
{ // multiple statements indented
}
else if (condition2)
{ // multiple statements indented
}
else if (condition3)
{ // multiple statements indented
}
else
{ // multiple statements indented
}

while loop

while (condition)
{ // multiple statements indented
}

for loop

for (int i = 0; i <= 20; ++i)

{ // multiple statements indented
}

do/while

do
{ // multiple statements indented
} while (condition);

switch statement

switch (value)
{ case value1: case value2:
// multiple statements indented
break;
case value3:
// multiple statements indented
break;
default:
// multiple statements indented
break;
}

Documenting user-defined classes

When using an object oriented programming language, such as C++, programmers often create
their own classes and then declare objects of these class types. These programs are frequently
composed of several files — one or more header files containing class definitions, implementation
files containing class functions, and a file containing the main program. The following describes
what documentation should appear in each of these files.
Header files

Documentation in the header file must clearly describe the class interface. That is, the task
performed by each member function should be described so that a client program which has
declared objects of this class type will know exactly what this class can do. This documentation
should be written so even a non-programmer can understand it. Header file documentation
should appear before the class declaration statement and contain the following.

Class name: Use a descriptive name beginning with a capital letter. Other words
within the name should have the first letter capitalized, like Circle or
RationalNumber.
Written by: Your name. list all programmers and sources.
For: Course name Course time Project id
Purpose: Tell what the user program can expect from this class. Describe what
the class represents. This should be implied by the class name, but be
more specific.
Member functions: list and describe briefly the tasks performed by each class function.
list constructors and public and protected functions first, private
functions last. Parameter lists should be described so the client
program will know how to call this function.
Member data: list each data variable and briefly describe its purpose.

Here is an example:

// Class name: Date

// Written by: programmer name
// For: CS 202 1:30 MWF Project #3
// Purpose: Objects of this class type will keep track of the
// month, day and year of a Date value. The program
// which uses this class can declare and initialize
// Date objects, change a date or print a Date in
// the form m/d/y.
// Member functions:
 // Date(int = 1, int = 1, int = 1999)
// This constructor function will accept from the
// calling program initial values for month, day,
// year, in this order. Or it will assign the default
// date of 1/1/95. Will check for valid values.
// setdate(int, int, int)
// This function will assign new integer values of
// the month, day and year of the date. The
// parameters represent the new values to be
// assigned in order of month, day, year. Will
// check for valid values.
// printdate()
// This function will display the date in format
// of m/d/y when called from a client program.
// Member data:
// month
// integer variable representing month value 1-12
// day
// integer variable representing day value 1-31
// year
// integer variable representing year value
// (4-digit number)
//

Implementation files

This file should begin with the class name that the functions belong to and the programmer's
name, the class, time and project. For example,

#include <iostream.h>
#include "date.h"

// Class: Functions for class Date

// Written by: Programmer's name
// For: CS 202 1:30 MWF Project #3

Each function in the file should then be documented as shown in the function headers for the CS
202 example.
Main program file

This file should be documented as shown in the main program for the CS 202 example.