<< Back

How To Document and Organize Your C++ Code

On This Page


1. Introduction

Programming style is about how you organize and document your code. Style is more than a matter of aesthetic interest. A program written following a consistent style is easier to read, easier to correct and easier to maintain.

A program may be written only once, but is read many times:

Anything that makes a program more readable and understandable saves lots of time, even in the short run.

Most programmers agree that coding standards are important. The problem is that there is no single standard for C++. As a professional programmer, you must be prepared to adapt your style to the standards of your company or project.

This course follows often-used industry coding standards. Some portion of the grade for most programming assignments is based on your coding style and how well it conforms to this document.

2. Naming Conventions

2.1. Use Meaningful Names

Choose names that suggest their purpose. Good names help you understand the problem you are solving.

2.2. Variable Names

There are two commonly-used styles you may use. However, you must be consistent and only use one of them in a program. The instructor's preference is the first style.

  1. Start with a lower-case letter and use uppercase letters as separators. Do not use underbars ('_').
    int myVar
  2. Use all lower case letters and use underbars ('_') as separators.
    int my_var

2.3. Constant Names

Use all capital letters and use underbars ('_') as separators.

const int MY_CONST = 1;

2.4. Function Names

There are two commonly-used styles you may use. However, you must be consistent and only use one of them in a program. The instructor's preference is the first style.

  1. Start with a lower-case letter and use uppercase letters as separators. Do not use underbars ('_').
    int myFunction()
  2. Use all lower case letters and use underbars ('_') as separators.
    int my_function()

2.5. Class Names

Start with an upper-case letter and use uppercase letters as separators. Do not use underbars ('_').

class MyClassName

3. Comments

Comments are explanatory notes for the humans reading a program. With good name choices, comments can be minimal in a program. The only required comments are block comments at the beginning of each file and before each function declaration.

Block comments are a region of code (the "block") used to describe another region of code such as files and functions. In this course you must write block comments for the entire files and for each function. See the follwong sections for descriptions of file and function block comments.

One other time to add comments, other than block comments, is when your code is unusual or obscure. When something is important and not obvious, it merits a comment.

3.1: File Comment Block

Every source file must have a comment block at the top containing the course number, assignment number, and purpose of the file. For example:

/**
    CS-11 Asn 2: Calculates the total of 6 checks
    @file checks.cpp
    @author Ed Parrish
    @version 1.1 4/10/20 
*/

One or two lines is usually sufficient to explain the purpose.

Always include the following tags:

3.2: Function Comment Block

Always add a comment block before each the function prototype (declaration). For example:

/**
    Encodes a single digit of a POSTNET "A" bar code.
    @param digit the single digit to encode.
    @return a bar code of the digit using "|" as the long bar
    and "," as the half bar.
*/
string encode(int digit);

On the first line describe the purpose of the function.

Where appropriate, include the following tags as well:

3.3: Example Program Documentation

Look at the following short program for a brief example of properly-documented source code.

/**
    CS-11 Asn 6: Calculates the area of a circle and the volume of a sphere.
    @file sphere.cpp
    @author Ed Parrish
    @version 1.1 3/17/20
*/

#include <iostream>
#include <cmath>
using namespace std;

const double PI = 3.14159;

/**
    Returns the area of a circle with the specified radius.
    @param radius The radius of the circle.
    @return The area of the circle.
*/
double area(double radius);

/**
    Returns the volume of a sphere with the specified radius.
    @param radius The radius of the circle.
    @return The volume of the sphere.
*/
double volume(double radius);

// Controls operation of the program.
int main(void) {
    double radius_of_both, area_of_circle, volume_of_sphere;

    cout << "Enter a radius to use for both a circle\n"
            << "and a sphere (in inches): ";
    cin >> radius_of_both;

    area_of_circle = area(radius_of_both);
    volume_of_sphere = volume(radius_of_both);

    cout << "Radius = " << radius_of_both << " inches\n"
            << "Area of circle = " << area_of_circle
            << " square inches\n"
            << "Volume of sphere = " << volume_of_sphere
            << " cubic inches\n";

    return 0;
}

// Returns the area of a circle with the specified radius.
double area(double radius) {
    return (PI * pow(radius, 2));
}

// Returns the volume of a sphere with the specified radius.
double volume(double radius) {
    return ((4.0 / 3.0) * PI * pow(radius, 3));
}

3.4: How to use Doxygen

The Doxygen tool examines the declarations and block comments of your code to produce a set of HTML pages describing to programmers how to use the code. Other tools exist including Ccdoc. The pages produced by these tools describe your code to other programmers. For an example of the documentation produced, see the Introduction to CcDoc.

To install and use Doxygen in a terminal window follow the instructions at: C++ Compiler Help

To configure Doxygen to run with TextPad, see the TextPad instructions for: Configuring the Documentation System.

4. Curly Braces

A fervent issue of great debate in programming circles is placement of curly braces. Either of the following two styles is acceptable in this course:

  1. Place the initial brace on the same line as the keyword and the trailing brace inline on its own line with the keyword:
    if (condition) {
        ...
    }
    
    while (condition) {
        ...
    }
    
  2. Place brace under and inline with keywords:
    if (condition)
    {
        ...
    }
    
    while (condition)
    {
        ...
    }
    

The first style is traditional for Unix and C programmers and is the personal preference of the instructor and Bjarne Stroustrup.

4.1. When Braces are Needed

All if, while and do statements must either have braces or be on a single line. This helps to make sure someone adding a line of code does not forget to add braces.

5. Whitespace

Always layout your source code so that elements that are part of a group go together.

5.1. No Tab Characters

Pressing the Tab key is the easiest way to align indented code. However, it is difficult to impossible to read source code if your tab settings are different than the author(s) of the file.

The easiest solution is to set text editors to replace tabs with spaces

Another option is to use a program named Artistic Style (astyle) to convert tabs to spaces. Artistic Style is installed with Cygwin and you can use it by typing at the command prompt. For the Mac see the Mac App Store. To fix your souce code for indentations and tab characters before submitting, use:

astyle -A2 -s4 myfile.cpp

or if you like the opening curly braces on a new line use:

astyle -A1 -s4 myfile.cpp

For more information see the astyle manpage or get help at the Cygwin command prompt by typing:

astyle -h

Notice that Artistic Style changes the tabs in your code statements but not in your comments. Thus you still need to verify there are no tabs in your comments.

An easier way to remove tabs is to set your text editor to substitute the correct number of spaces for a tab character. In TextPad, this is available under the Configure => Preferences menu. From the dialog window that appears, expand Document Classes and C/C++ to find the Tabulation settings. Check both of the check boxes:

Press the OK button to apply the changes.

5.2. Line Length

Limit your line lenght to about 80 characters since long lines make it difficult to read your program code, especially on smaller screens.

5.3. Spacing Around Operators

Always put spaces before and after binary operators, including << and >>. This improves the readability of expressions. For example:

cin >> a;
double c = -a * b + 42 - d / 100;
cout << c << endl;

5.4. Indentation

Always indent within curly braces. Use 3 or 4 spaces for each indentation level, but be consistent. For example:

int func() {
    int dragons = 0;
    cout << "Enter the number of dragons: "
    cin >> dragons;
    while (dragons > 0) {
        Dragon d = getDragon();
        if (d.isFriendly()) {
            rideDragon();
        }
        dragons = dragons - 1;
    }
    return 42;
}

5.5. if-else-if-else Formatting

Always line up if statements with their associated else statement. Beyond that, there are two common styles that you may use:

  1. Place the initial brace on the same line as the keyword and the trailing brace inline on the same line as the next statement. For example:
    if (condition) {               // Optional comment
        ...
    } else if (condition) {        // Optional comment
        ...
    } else {                       // Optional comment
        ...
    }
    
  2. Place brace under and inline with keywords. For example:
    if (condition)                 // Optional comment
    {
        ...
    }
    else if (condition)            // Optional comment
    {
        ...
    }
    else                           // Optional comment
    {
        ...
    }
    

6. No Magic Numbers

A magic number is a numeric literal that is not defined as a constant. It's magic because no one has a clue what it means after 3 months, including the author. From widespread use, -1, 0, 1, and 2 are not considered magic numbers.

Whenever you type a number in your code, use a constant instead to document the number's meaning. In C++, you declare constants, which are variables that cannot change, using the keyword const. You may use local constants within functions, member constants declared in a class, or global constants declared outside of any class or function. Also use const for arrays of numbers that are read-only.

const int MY_CONSTANT = 10;
const int DATA[] = { 10, 20, 30 };

Because of their special meaning, write constants in all upper case and use underbars ('_') as separators.

7. No Global Variables

A global variable is declared outside of any function and can be accessed by any function in a program. For example, in the following code myGlobal is a global variable.

#include <iostream>
using namespace std;

double myGlobal = 0;

int main(void) {
    // main function code
    myGlobal = 1;
}

void anotherFunc() {
    myGlobal = 2;
}
// other functions

There is rarely a need to use global variables. Moreover, global variables make a program harder to understand and to maintain. Thus, for this course, do NOT use global variables.

<< Back