Style Guidelines

Comments

In C++ there are two ways to insert comments: // and /* */. You should use // for writing comments within your program and reserve /* */ for commenting out blocks of code when debugging. Always leave a space between the comment character and your text e.g "// Test" instead of "//Test".

Each program must begin with a comment block that specifies the file name, author, course, date created and a description of what the program does.

//--------------------------------------------------------
// File: hw1.C
// Author: John Doe
// Course: CS1129
// Date: Jan 9, 2005
// 
// Program takes an integer as input and outputs the
// the next prime number greater than the input.
//--------------------------------------------------------

Each function must begin with a header block that lists the preconditions (things that are required for the function to work as expected) and postconditions (the effects of executing the function).

//--------------------------------------------------------
// Precondition: size is the size of array a.
// 
// Postcondition: a[0] through a[size-1] will be
// filled with random values.
//--------------------------------------------------------

void fillArray(int a[], int size) {
    ...
}

Each class must begin with a header block that describes its purpose. Member functions and data members must also be commented.

//--------------------------------------------------------
// Class Employee
// Used to store payroll information for each employee.
//--------------------------------------------------------

class Employee {
  public:
    Employee();         // Default constructor
    double getSalary(); // Returns the employee's salary
  
  private:
    int employeeId;     // Employee SSN
    double hourlyRate;  // Rate of pay
    double salary;      // Employee salary	
};

There should be enough comments throughout the program to explain the algorithm that was used. However do not overcomment by adding lines that explain the C++ language. Assume the reader knows C++.

Indenting

Anything between a pair of braces { } should be indented 4 spaces from the braces. You should setup your editor to use spaces instead of tabs when indenting. We expect that every program you write will be perfectly indented since this is a standard required of all programmers.

Braces

We will use Java style braces to decrease code length.

// for loop
for (int i = 0; i < n; ++i) {
    sum += a[i];
}

// if-else
if (x < y) {
    x++;
}
else {
    y++;
}

Declarations

All variables must be declared at the beginning of a function and should be initialized if possible.

Variable Naming

Variable names should be meaningful and convey the usage of the variable. This will also lead to less comments needed in your program since it will be more readable. You should use mixed case when naming variables i.e. start the variable in lowercase then use uppercase to indicate the beginning of a new word. Use all caps for constants and separate each word by an underscore.

int timeOfArrival;

const int LIBRARY_SIZE;

Whitespace

Use of whitespace makes your code more readable. You should leave one space between operators and operands.

if ((base != 0) && (exponent > 1))
	answer = power(base, exponent);
else
	answer = simplePower(base, exponent);

Line Wrap

Lines of code should not wrap around when viewed on screen or when printed. As a general rule, you should not have lines longer than 80 characters.

Program Output

Your program output should be neat and well formatted. Make sure you output a newline at the end of every program, so that the command prompt will appear on a newline.

$prompt> g++ hello.C
$prompt> a.out
Hello World!
$prompt>