Coding Style Guide

globals comments indenting curly braces
return points format width break and continue
files and file contents statemens per line

Global Variables

Global variables are variables that are not declared inside of a function ( yes, main is a function ). They are EVIL, the only good globals are 'static const', which limits the scope and prevents them from being changed. Your programs will not have globals unless I direct you to use them for some reason, or they are 'static const'.
return to top

Comments

I want to see comments in your code, especially function/method block headers, and variable declarations. This means all functions or methods should have the input, output and return listed explicitly. There should be comments on anything that is not obvious. This includes complex code, or strange things that you don't completely understand. Remember C/C++ code is not self-documenting. The standard rule is: comment as if 6 months from now another programmer/student could understand it without you being there to explain it.
Here is an example function, with comments:


// input:  an integer array and the size of it
// output: none
// return: none
// notes: the contents of the array will be sorted low to high
void sort ( int arr[], const int size )
{
    for( int i = 0 ; i < ( size - 1 ); i++ )    // outer loop n-1 passes
    {
        for( int j = i ; j < ( size - 1 ) ; j++ )   // inner loop
        {
            if ( arr[j] > arr[j+1] )            // if the order is wrong
            {                                   // swap the element
                // swap the two elements
                int tmp = arr[j];
                arr[j] = arr[j+1];
                arr[j+1] = tmp;
            }
        }
    }
}

return to top

Indenting

Every time a new block of code starts it should be indented, and evenly indented. Indent between 4 to 8 spaces, I use 4 spaces. Spaces should always be used instead of tabs. Using tabs can cause the code not to display the same in any editor, this is called tab damage.
Here is an example:


// input:  two integers x and y
// output: reciprocal message if y < 0
// return: the value of x raised to the y power
int powi( int x, int y )
{
    if ( y < 0 )
    {
        // if y < 0 then the answer would be a float
        // we are going to return the reciprocal instead
        // so we can still return an int
        cout << "calculating the reciprocal power" << endl;
        y *= -1;    // y is now positive
    }
    int rval = 1;   // a variable for the result
    while ( y > 0 ) // multiply x by itself y times
    {
        rval *= x;
        y--;
    }
    return rval;
}

Continuation of the same line of code should also be indented. Here is an example:


    cout << " this is an example of a line continuation "
        << ", which is handy when a line of code won't fit." << endl.

return to top

Curly Braces

I want everyone to use what are called East Coast Braces, not West Coast Braces.

Here is an example of west coast which is BAD.


    for( int i = 0; i < 10 ; i ++ ) {
        cout << i << endl;
    }

Here is an example of east coast which is GOOD.


    for( int i = 0; i < 10 ; i ++ )
    {
        cout << i << endl;
    }

East coast braces are easier to see if you forgot one, and helps make indenting easier to figure out when it gets goofed up.
return to top

Return Points

No function or method should have more than one(1) return point. The exception to this rule is if the function is recursive.

Here is what I DON'T want to see.


bool func( int n )
{
    if ( n > 10 )
    {
        return true;
    }
    else
    {
        return false;
    }
}

Here is the previous code rewritten to have only one return.


bool func( int n )
{
    bool rval = false;
    if ( n > 10 )
    {
        rval = true;
    }
    return rval;
}

This will help you avoid some annoying compiler warnings, and some possible error conditions in your code. Many programmers miss every condition that is possible and fail to always return a value from a function, this will prevent that error.
return to top

The only things that belong in a header file are prototypes, declarations, typedefs, #defines, and any required extern declarations.
The only times that implementation should occur in a header file are : if the class is templated, or if you are inlining class methods. In both of those cases the code must be in the header. Inline methods for the purpose of my classes may not exceed 3 lines of code.
Never include a cpp file, only header files should be included. Any source file should get compiled to object code, and objects should be linked together to create executables.

return to top

Statements per line

I only want to see one statment per line.

Here is what I DON'T want to see.


foo = y; bar = z;
if ( foo == bar ) x = 5;

Here is the correct form of the above code


foo = y;
bar = z;
if ( foo == bar )
    x = 5;

return to top

Coding Style Guide

Global Variables

Comments

Indenting

Curly Braces

Return Points

Format Width

Break and Continue

Files and File Contents

Statements per line