CIS Logo SVC Logo

   Computing & Information Systems
   Department

 

Schoology Facebook        Search CIS Site      Tutorials

Software Design Using C++



C++ Formatting and Documentation



Formatting


Although a program should first of all meet its specifications, there are important considerations other than correctness. Programs are written not just to be run, but also for others to read. Pity the poor maintenance program who is going to have to read and decipher your work several years from now! Make this person's job easier through good use of indentation, spacing, descriptive identifiers, and general neatness. It is typical, for example, to vertically align opening and closing braces, although there are a few authors who do not do this. One also should put blank lines between major sections of the program, such as between functions. It also helps a lot to put spaces after most types of punctuation, such as commas, and on both sides of binary operators, such as +. Indenting properly can do much to improve the ease of reading a program. It is typical to indent the "loop body" of a loop by about 3 spaces. Similarly, one should indent the body of a function about 3 spaces as well as the choices inside of an if/else. Look at the short example below as a guide.

Documentation


If you provide good documentation, that maintenance programmer is going to bless you, not curse you! There is both internal and external documentation. The internal documentation is contained within the program file(s) and includes a description at the top giving the inputs, overall processing, and outputs of the program. This section of documentation is essentially a brief user manual. A stranger who reads this section should know what your program does as well as how to set it up and run it.

The documentation at the top of a program file should list the date, the name of the author, the names of any other people who contributed to it, and any references used in any significant way (books, web sites, etc.). This allows both you and others to know at a glance what sources were used in producing this program.

Internal documentation also includes a comment section for each function, listing what is being passed into it via the parameters, what the function's main task is, and what values are being passed back out via the parameters or function name. (For object-oriented programming, the implicit object is also used to send values in and out.) The Given/Task/Return style of function comments is suggested. In this, the "Given" section lists each parameter that is used to send a value into the function. Beside the name of the parameter, a description of its meaning is listed. The "Task" section describes the overall task of this function. It tells the reader what this function does if the function is called. Always describe the task in terms of the parameters. Try NOT to use items outside of the function in this description. The "Return" section lists each parameter (and its meaning) that is used to send a value back out of the function. It also lists any value returned in the function name and its meaning.

Internal documentation also includes a description of each user-defined class. External documentation is separate from the program and may consist of items like the specifications, various diagrams, a record of testing, etc.

Example




/* Filename:  area3.cpp

   Author:  Br. David Carlson

   Other Contributors:  None

   References:  C++ from the Ground Up, 2nd ed., by Herbert Schildt

   Date:  January 4, 2000

   Revised:  June 26, 2000

   This program asks the user to enter the length and width of a
   rectangle.  It then computes and prints the area of the rectangle.
   A warning is printed if the user enters a width larger than the length,
   but the program still prints the area in such a case.
*/

#include <iostream>

using namespace std;


// Function prototypes:

void Explanation(void);

void GetValues(float & Length, float & Width);

float ComputeArea(float Length, float Width);

void PrintArea(float Area);


int main(void)
   {
   float Length, Width, Area;

   Explanation();
   GetValues(Length, Width);

   if (Width > Length)
      {
      cout << "Warning: the width you entered is larger than the length.";
      cout << endl << "The area will still be found." << endl;
      }

   Area = ComputeArea(Length, Width);
   PrintArea(Area);

   return 0;
   }

/* Given:  Nothing.
   Task:   To ask the user for the length and width of a rectangle, insisting
           on positive values for both, and to return these values via the
           two parameters.
   Return: Length   The length entered by the user.
           Width    The width entered by the user.
*/
void GetValues(float & Length, float & Width)
   {
   cout << "Enter the rectangle's length: ";
   cin >> Length;

   while (Length <= 0)
      {
      cout << "Error: Length must be positive.  Re-enter: ";
      cin << Length;
      }

   cout << "Enter the rectangle's width: ";
   cin >> Width;

   while (Width <= 0)
      {
      cout << "Error: Width must be positive.  Re-enter: ";
      cin >> Width;
      }
   }

/* Given:  Length   The length of the rectangle.
           Width    The width of the rectangle.
   Task:   To compute the area of this rectangle.
   Return: The area in the function name.
*/
float ComputeArea(float Length, float Width)
   {
   return Length * Width;
   }

/* Given:  Nothing.
   Task:   To print an explanation of what the program does.
   Return: Nothing.
*/
void Explanation(void)
   {
   cout << "This program computes the area of a rectangle." << endl;
   cout << "You will be prompted to enter both the length and width.";
   cout << endl << "Enter a real number for each." << endl;
   cout << "The program will then compute and print the area.";
   cout << endl << endl;
   }

/* Given:  Area    The area of a rectangle.
   Task:   To print Area.
   Return: Nothing.
*/
void PrintArea(float Area)
   {
   cout << "The area is: " << Area << endl << endl;
   }

Other Concerns


Efficiency is also of some importance. Don't needlessly waste computer time or memory space. In particular, don't waste a lot of it. If there is a tradeoff between efficiency and a clear design, having a clear design is probably better (unless you would waste a lot of time or space to get it). Of course, it also does not make sense to waste a lot of your own time (or your employer's) to make minor speed improvements to a program that will be rarely used and runs fast enough as is.

Here are some "thou shalt not" rules of thumb: Don't use an obscure method when clear methods are available. Do not have a variable do double duty, as in using a variable called Total to hold both the total of some data items, and later the average of these data items. (The name sum, not an average. Don't confuse the readers of your program!) Do not have a section of program do double duty in a non-obvious way. The intention of each section of code should be reasonably clear.

Related Items

Back to the main page for Software Design Using C++

Author: Br. David Carlson with contributions by Br. Isidore Minerd
Last updated: January 07, 2015
Disclaimer