Software Comments in C and C++ code

With decades of experience writing and supporting software for many different customers, we have seen many variations of coding styles and guidelines, and with them, many different variations of comment styles.

While each company has their own preferred method of including comments in software, and details regarding the comment delimiters, line spacing, etc., a general outline of the approach we have seen work best, at least for C and C++ based software, is as follows:

  • Each code file (i.e. .c, .cpp, etc. file ) in a source tree should have a corresponding .h file in which the ‘public’ or ‘user visible’ function prototype definitions and public type and constant definitions are defined. A developer using functions coded in a .c or .cpp file should only have to look at the corresponding .h file in order to use the code in the .c file. 
        math_functions.h
    math_functions.c
  • A ‘header’ comment including copyright information and a very short description of the purpose of a file should appear at the top of every file in the source code. This includes both header files and code files. 
    /*
    Copyright 2016 Acme Inc. All Rights Reserved

    math_functions.h - math library routines
*/
  • Comments describing the API (Application Programming Interface) for a ‘public’ function should be with the function prototype definition in the applicable header (.h) file. 
    /*
    Copyright 2016 Acme Inc. All Rights Reserved

    math_functions.h - math library routines
*/

/*   
    32 bit divide function

    parameters:
    divisor  - 32 bit divisor
    dividend - 32 bit dividend

    returns:
    dividend / divisor
*/
long divide_32(long dividend, long divisor);

/*   
    fibonacci sequence  
 
    parameters:
    num  - integer number

    returns:
    value of fibonacci sequence for n = num.
    fib(0) = 0, fib(1) = 1, fib(2) = 1, fib(3) = 2, fib(4) = 3
    etc. 
*/
int fib(int num);

/*
    ... other functions in math.h & math.c
*/
  • Comments should not be present at the start of the code implementation for individual functions in the .c file if those functions are ‘public’ and part of the module’s API. In other words, if the function’s API comments are in a header file, they should not be repeated in the .c file.
    • /*
    Copyright 2016 Acme Inc. All Rights Reserved

    math_functions.c - math library routines
*/

long divide_32(long dividend, long divisor) {
    return dividend / divisor;
}

int fib(int num) {
    int val;
    if (num == 0 )
        val = 0;
    else if (num == 1)
        val = 1;
    else {
        int f0 = 0;
        int f1 = 1;
        for (int i = 0; i <= num-2; i++ ) {
            val = f0 + f1;
            f0 = f1;
            f1 = val; 
        }

    return val;
}
  • Private functions that are local to a specific .c file should be commented in the .c file itself. These would typically only be referenced by someone editing the .c file.
  • The code in a .c file should, to the greatest extent possible, comment itself. In other words, the instructions in the code should be written in a way that the purpose and operation of the code lines are clear by looking only at the code. For example, choose variable names that bear some relationship to the purpose of the variable. i.e. ‘result’ for the resulting value that will be returned from a function. i.e. ‘pDescriptor’ for a pointer to a descriptor in a device driver ring.
  • Comments should only be added within the code implementation for a function to explain an obscure calculation or operation that is not evident from reading the code. Such comments should explain something about how the implementation works.

The objective of commenting code is to make it easier for someone to support and understand the code. To this end, the less text there is to look through, the better. In one example we ran into, the coding standard had some verbiage to the effect that comments should be used ‘copiously’. This led a novice programmer to generate thousands of lines of code like this:

// declare variable i
int i;

// clear the initial value of i
i = 0;

// use i to loop 10 times
for ( i = 0; i < 10; i++ ) {

     j = j + 1; // increment j

}

There was a separate comment line for practically every line of C code. We feel the following, with no comments, is actually more readable, much quicker to scan through, and is easily understood:

for (int i = 0; i < 10; i++) {

    j = j + 1;
}

Programmers using languages other than C/C++, for example Python, other ‘scripting’ languages like Perl and PHP, or some types of microcode, can all benefit from picking up on the spirit of the above ideas.

We hope this small note provides some useful guidelines for making your code more supportable.
Please contact us for help with your project

Comments are closed