C++ Programming Style and Documentation Guidelines

1. All program files begin with a comment block like this one:

// file name: aprog.cpp
// programmer: Mortimer G. Slithey
// class: CSC 256.S03
// instructor: Monty P. Ython
// first written: 12/3/96
// last modified: 12/9/96
// related files: aprog.h, queue.cpp, queue.h
//
// purpose: The program produces a ranked class listing from data found in the input file
// “class.txt”.
with, of course, your name instead of Slithey's, your class instead of CSC 256.S03, and so on.

2. All functions (including the main) will have a comment block giving pre: and post: conditions.

The conditions must clearly document the state of any relevant parts of the system before the function can run and after the function finishes. These comments may be informal, if necessary, but must be clear and unambiguous.

int Lowest (int Limit)
// pre: The input stream cin contains at least three integers separated by blanks.
// There are no non-integer values in cin. "Limit" has a value between 0 and 5.
//
// post: Limit is unchanged. All integer values in cout have been read in. The lowest value
// read in is returned as the value of the function.
//

3. All identifiers (variable, constant, and function names, etc) must be mnemonic.

    int class_size;

rather than

    int c;

4. Use declared constants whenever possible rather than literals imbedded in the code.

    const float tax_rate = 0.06;
	.
	.
	.
    tax = total * tax_rate;

rather than

    
    tax = total * 0.06;

5.Use indentation and blank lines (white space) to clarify the structure of your program.

     .
     .
     .
   cin >> limit;
   counter = 1;
   while (counter <= limit)
   {
     cout << "Enter an integer grade value" << endl;
     cin >> agrade;
     total = total + agrade;
     counter++;
   }

   if (limit > 0)
     average = total / limit;
   else
     average = 0.0;

rather than

     .
     .
     .
cin >> limit;counter = 1;
while (counter <= limit){
cout << "Enter an integer grade value" << endl;cin >> agrade;
total = total + agrade;
counter++;}
if (limit > 0)
average = total / limit; else average = 0.0;

To some extent, exactly how white space is used is a matter of individual style. However, you must use indentation to indicate levels of control. Also, consistent use of white space within a program is important.

6. Function interfaces must be explicit

Any values used or modifed by a function must be passed to it in the function's parameter list. Avoid the use of global variables.

7. Strive for functional cohesion

Every function should have one easily-stated purpose, accomplishing only one logical task.

8. Formal specifications

Where possible, the pre: and post: conditions for a function should be written as formal specifications in predicate logic.

9. Remove extraneous comments and code

Often programmers will put in temporary comments or diagnostic output statements as debugging tools. Also, sometimes sections of code are "abandoned" as the program is written and errors are found. None of these things should remain in the program when it is handed in.

10. Avoid memory leaks

When dynamically allocated space is no longer needed, use delete to return it to the system. Do not simply change the value of all the pointers to the space.

11. Create explicit constructors and destructors

Do not rely on the default constructors, destructors, copy constructors and assignment operators that C++ provides for programmer-created classes. This is particularly true of classes which involve dynamic memory allocation. Instead, write your own class methods.

12. Ensure that all variables and objects are initialized before they are used

By preference, include an initialization (assignment for variables, constructor for objects) in the declaration of a new entity. For example, if you know the first value that a variable should take, use:

  .
  .
  .
  int x=0;

rather than

  .
  .
  .
  int x;
  .
  .
  .
  x=0;