Mel Corley's Home     |     home

C++ Coding Standards
Documentation Guidelines:

The beginning of the program should contain the following documentation heading:

         1         2        3         4         5         6         7
123456789012345678901234567890123456789012345678901234567890123456789012345
///////////////////////////////////////////////////////////////////////////
//                                                                       //
// Your Name                                                      userID //
// Program X                                Due HH:MM:SS a.m. MM/DD/YYYY //
// Give a complete description of the problem to be solved.              //
//                                                                       // ///////////////////////////////////////////////////////////////////////////
Each function should contain the following documentation heading:

///////////////////////////////////////////////////////////////////////////
//                                                                       //
// functionName                                                          //
//                                                                       //
// Give a complete description of the function                           //
//                                                                       //
// Inputs:   nameOfFirstParam  : first parameter's description           //
//           nameOfSecondParam : second parameter's description          //
//             (repeat until you have described all parameters)          //
//                                                                       //
// Returns:  returnVal : description of what is returned to caller       //
//                                                                       //
// Calls:    list of functions called by this function, if any           //
//                                                                       //
///////////////////////////////////////////////////////////////////////////

Variable declarations:
Use mnemonic variable names.
Line up your declarations (see i, ssn, payRate, groupId below).
Use comments to explain variables whose names don't make their use obvious.
int    i, j, k;            // used for looping
int    ssn, hoursWorked;
float  payRate, salary, stateTax, fedTax;
char   groupId;
AVOID GLOBAL VARIABLES!!
When passing a variable to another function, do not use the same variable name for the formal and actual parameters. This means that you must not use the same variable name when calling a function that you use in the called function.

Executable code section:
Always put a blank line between declarations and the executable section of your functions.
Put at most one statement per line.
Put a space before and after operators and comparators (such as =, ==, >, +, -, *, etc.).
Indent bodies of blocks 3 spaces.
Always put a comment after an end brace (}).
For if-else statements, line up the if with its corresponding else.
Avoid long lines. Try to keep lines less than 80 characters long.
Examples:
            if (a > b)
               c = a;

            if (a > b)
               c = a;
            else
               c = b;

            if (a > b)
            {
               c = a;
               d = b;
            }  // then
            else
            {
               c = b;
               d = a;
            }  // else

            while (a > b)
            {
               sum += a;
               a--;
            }  // while

            for (i = 1; i < 10; i++)
            {
               cout << "i = " << i << endl;
               j *= i;
            }  // for

            if (grade == 'A')
               acount++;
            else if (grade == 'B')
                    bcount++;
                 else if (grade == 'C')
                         ccount++;
                      else if (grade == 'D')
                              dcount++;
                           else if (grade == 'F')
                                   fcount++;
                                else cout << "Invalid grade\n";

            for (i = 1; i < 10; i++)
               for (j = 1; j < 5; j++)
                  total += i * j;

Use in-line documentation to explain sections of code within functions. Your documentation MUST make the functionality of the code obvious.

      // Read in and sum the grades.
      while (....) ...

      // Calculate the amortized interest rate.
      ...

      // Check for possible divide-by-zero error.
      ...
Put the following comment at the end of each function:

      }  // functionName