Programming Style Guidelines

Header Comments

// Adds two numbers- What the contents of the file are for
// Project #1 Add Program- The assignment name and class if the file is part of a class program assignment.
// CS 13011
// John H. Doe- Who wrote the program
// 9/14/99  - The date the program was created or last modified 

Identifiers

	int tmp;
	
	// swapping values of a and b
	tmp=a;
	a=b;
	b=tmp;
	

Declaring Variables

int n;
cin >> n;

Constants

int calc = 20 * 90;

Use:

const int numStudents = 20;   // number of students
const int lowestA = 90;	      // lowest score for A
int calc = numStudents * lowestA;

Use named constants instead of varables: if a variable is never updated except for initialization, make it a constant. For example: If

int calc = numStudents * lowestA;

const int calc = numStudents * lowestA;

Comments

Use the C++ style comments (//). Leave the C-style comments (/* ... */) for special purposes such as commenting out portions of code.

"Educational" comments explaining what the particular construct means in C++ (unless it is relatively obscure or not obvious) should be avoided. You can assume that the reader is familiar with C++. Use "production" comments that explain the purpose and intent of the code. For example:

++total; // increment total educational comment, avoid

++total;  // another element is processed production comment, use

Put an inline comment for every variable declaration (except for obvious cases such as loop variables used right after the declaration) explaining what this variable is for. Comment a function prototype. Put more extensive comments in front of a function definition, possibly explaining the purpose for the parameters and the function's return value:

//  sorts an array a[] using quicksort method
//  returns the smallest element
int qsort(int a[]){
   ...
}

Line Spacing, Line Length

// read in the valuesThese lines are hard to read.  It is hard to see what the different parts of the code are.
cout << "Enter ...";
int n1, n2;
cin >> n1 >> n2;
// calculate
int total = n1 + n2;
// print out the results
cout << "Total is " << total << '\n';

Use:

// read in the valuesThese lines are much easier to read.  The placement shows the different "paragraphs" of code.
cout << "Enter ...";
int n1, n2;
cin >> n1 >> n2;

// calculate
int total = n1 + n2;

// print out the results
cout << "Total is " << total << '\n';

Use line size of 75-80 characters: about the width of the text on a page in a book. Longer line sizes make the program hard to read.

Indentation

Sequential statements should line up:

int v;
cin >> v;
v *= 2;
cout << v;

Note return statement is a sequential statement. It should line up with the rest of the sequential statements.

Conditional statements should indent for the statements that they contain:

if (s < 0)
    cout << s; Indent then statement
else
    cout << (s * 2);Indent else statement

If you use braces (curly brackets) for a block of code in the conditional statement place them as follows:

if (s < 0 ) {
    ++s;	     indent then statements
    cout << s;
} else { 
    --s;     indent else statements 
    cout << tmp;
}	    

Multi-way if (if-else-if sequences of similar nature) should be indented as follows:

if (i==1) {
    i+=1;	then action of the first if indented
    cout << i;
} else if (i < 1) {
    i+=2;       then action of the second if indented
    cout << i;
} else if (i > 1) {
    i+=3;       then action of the last if indented
    cout << i;
}

switch should be indented as follows:

switch(i) {
case 1:
    i+=1;
    cout << i;
    break;
case 2:
    i+=2;
    break;
default: 
    cout << i;
}

Loop body should be indented as follows:

while (s > 0) {
    cin >> s; Indent inside loop body
    ++s;
}

Nested conditional and loop statements should be properly indented:

while (s < 0) {
    cin >> s; Indent inside loop body
    if (s < 0 ) {
       ++s;      Indent inside then-statements
       cout << s;
    }
}

int computeMax(int i, int j) {
   if (i > j)
      return i;
   else
      return j;
}

Protection Against Multiple Inclusion

#ifndef MYHEADER_H
#define MYHEADER_H
class MyClass {
 ...
};
const int myConst; 
#endif // MYHEADER_H

Classes

Do not use void to signify lack of parameters in a function. Do not place a semicolon after inline function definition.

Here is an example:

class MyClass{
public:
   MyClass(){data_=0;} note, no trailing semicolon
   void set(int);
private:
   int data_;
};

void MyClass::set(int data){
   data_=data;
}

No Input Validation

The style guide was originally compiled by Michael Collard, additions are due to Debbie Stoffer and others.