Programming Guidelines

In an effort to produce high-quality, readable and maintainable source code, we try to maintain guidelines outlining our expectations for programming standards. Additionally, these guidelines make an effort to keep sections of code written by different programmers stylisticly consistent to improve overall readability and maintainability.

---

• High-quality, readable, maintainable code is Priority 1. This applies even if it means somewhat inefficient code. Performance bottle-necks can be dealt with after debugging phases.

• Avoid 'clever' tricks. It is often tempting to use 'clever' tricks in an effort to squeeze as much performance out of code and sometimes to produce as few lines of code as possible. This is a sure-fire way of introducing obscure bugs and virtually garantees unreadable code. During the development phase, saving a few extra CPU ticks per frame is not important.

• Functions should generally avoid writing data into its arguments using address references (e.g., void someFunc(int &arg)). While this is a 'clever' technique that can reduce the number of lines of code and may even be slightly faster, this is a very good way to introduce obscure bugs into otherwise well written code.

• Magic Numbers should never be used regardless of comments that explain them. Instead, named constants should be used.

• Class Definitions should define their member functions and variables first by 'public' followed by 'protected' and finally 'private'. Please see naming conventions for expected name formatting.

• All code must be Commented properly and all functions should be commented using Doxygen syntax. Comments should be concise but should contain enough information about what's happening and any assumptions that are made.

• Function, Enum and Class Member Function Comments must follow the Doxygen formatting syntax and must be in a '*.cpp' file, not a header file unless the entire class or enumeration is both declared and defined within the header file.

• Class Member Variable Comments must follow the Doxygen formatting syntax and should contained in the header file defining the class.

• Naming Conventions for functions, classes, typedefs, variables, etc. are expected to be in the following format:

// Local Variable
int localVariable;
 
// Class Member Variable
int mMemberVariable;
 
// Typedef, Class, Enum, Struct, Etc.
type ObjectName;
 
// Function and Member Functions
void someFunction();

• Use Descriptive names for Variables and Functions. To many times variables and function names are either too short or don't describe what their intended use is. Please, however, do not go overboard with your naming.

• Pointer declarations are generally defined with the splat adjascent to the identifier:

// Preferred Pointer Declaration
SomeType *myType;
 
// Alternative Acceptable Declarations
SomeType* myType;
SomeType * myType;

• Bracket Placement & Formatting, particularly around conditional blocks, should always start on a new line and not on the same line as the conditional. Additionally, conditional blocks should not contain brackets around a single line of code.

////// Good
if(expression)
{
    // Execute Line 1
    // Execute Line 2
    ...
    // Execute Line N
}
 
if(expression)
    // Single Line of Code
 
////// Acceptable as it improves readability
if(expression)
{
    // Single Line of Code
}
else
{
    // Execute Line 1
    // Execute Line 2
    ...
    // Execute Line N
}
 
////// Bad
if(expression) {
    // Execute Line 1
    // Execute Line 2
    ...
    // Execute Line N
}
 
if(expression)
{
    // ...
} else {
    // ...
}
 
if(expression)
{
    // Single Line of Code
}