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.
// John H. Doe- Who wrote the program
// 9/14/18  - The date the program was created or last modified 

Identifiers

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

A function should contain a verb in active tense: getValue(), a variable should contain a noun: studentNumber. An identifier should contain dictionary words rather than single letters like: a, b, x1, x2. No slang, personal names, (English) idioms: fido(), curve_ball. Use only standard acronyms: GUI. Do not encode variable type into its name: intVar. Identifier length is recommended under 5 words.

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';

write:

// 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

Independent sequential statements should line up:

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

Note that return-statement is a sequential statement and it should like up with the rest.

The bodies of conditional statements should be indented:

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

If you use curly brackets (braces) for the body of 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 processing multiple options) 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.