CodingStandards

Coding Standards

Outdated: Requires Reversion for C Standard

Naming

• Lower case is assumed, unless otherwise specified
• Abbreviations and acronyms shall be all upper case
• Constants shall begin each word with upper case

const int ConstantValue = 0;

• Macros shall be all upper case, each word will be separated by '_'
  • Avoid the use of macros in C++ methods, use lambda sequences.

#define SOME_MACRO(a) ( ... )

• Types shall have no prefixes, each word shall begin with upper case
  • When using C++, use class instead of struct, except when interfacing with the C library or system calls

class SomeType { ... };

• Method shall have no prefixes, each word shall begin with upper case

void SomeType::SomeMethod();

• Static variables shall be prefixed with 's', each word shall begin with upper case

int SomeType::sGlobalVariable = 0;

• Parameters shall be prefixed with 'p', each word shall begin with upper case

void SomeType::SomeMethod(int pParameterVariable)

• Locals shall begin with lower case, each word thereafter shall begin with upper case

int localVariable = 0;

• Use descriptive names
  • Do not use short cryptic names, names shall be self documenting to their purpose
  • Do not use alternative spellings, names shall be easy to type without looking up spelling
  • Exception: Short scope variables, like loop counters, may use shorter names if their purpose is obvious
• Use english names only, it is the preferred language in the software market

Indentation

• Scope braces shall follow the "Exdented Style"
  • Scope braces shall be indented 4 spaces to the right of the enclosing scope
  • Parameters shall be lined up with one parameter per line, to allow space for comments
• Declare each variable in a separate statement, this clarifies declarations
• Declaration of pointers '*' and references '&' shall have a space on the right, but not their left
• Binary arithmetic, bitwise, assignment, and the ternary operator shall be surrounded by spaces
• Comma shall be followed by a space but not preceeded, all other operators shall not use spaces
• Templates and parentheses shall have spaces on the outside, but not on the inside
• There shall be a space between control keywords (such as if and while) and parentheses, but not between methods/functions and their parentheses
• There shall be a space between a class/namespace and it's opening curly brace which shall be on the same line
• Do not use tabs, convert tabs to 4 spaces so the source looks the same under all environments

// Pure C function
void SomeFunction(int pSomeParameter, // Some parameter
                  int pAnotherParameter) // Another parameter
{
    int someLocal = 0;
    int anotherLocal = 0;
    if (pSomeParameter > 0)
    {
        if (pSomeParameter == pAnotherParameter) someLocal = someParameter;
        anotherLocal = anotherParameter + someLocal;
    }
}

// C++ class
class Example
{
public:
    // Comment for Example()
    Example() : mInteger(0), mString("string") {}

    // Comment for Example(int, float)
    Example(int pInteger,  // Comment for pInteger
            float pFloat); // Comment for pFloat

    // Comment for ~Example()
    ~Example();

    // Comment for mInteger
    int mInteger;

    // Comment for ExampleMethod()
    const char* ExampleMethod(float pFloat);

    // Comment for operator+(const Example&)
    int operator+(const Example& pOther);
private:
    // Comment for mString
    std::string mString;
};

const char* Example::ExampleMethod(float pFloat)
{
    if (pFloat > 0.0f) return "Hello";
    return "World";
}

int Example::operator+(const Example& pOther)
{
    return mInteger + pOther.mInteger;
}

Example::Example(int pInteger,
                 float pFloat)
                 : mInteger(pInteger)
{
    mString = ExampleMethod(pFloat);
}

Comments

• Use english comments only
• Use JavaDoc style comments "///" and "//* ... */"
• Comments shall be placed above the line they describe indented identically
• Parameters shall be comment on the same line
• At minimum every method/function declaration shall have a comment describing its purpose, parameters and return value

Files

• File names shall be treated as case sensitive
• C header files shall have the extension ".h" and shall be included using extern "C" { } directive
• C source files shall have the extension ".c"
• C++ header files shall have the extension ".h"
• C++ source files shall have the extension ".cpp"
• Assembly files shall have the extension ".asm"
• Compiled files shall have the extension ".o"
• Library files shall have the extension ".a"
• Headers shall have inclusion guards

#pragma once

#include <...>

• Headers shall be self contained
  • When a header is included, no other headers shall be required before it
• Headers shall be included using <>, project headers may be included using ""
  • Use appropriate naming for C headers

//C code
#include <stdlib.h>
//C++ code
#include <cstdlib>

• Include directives shall appear at the top of files
• Do not use absolute paths in include directives
• Every file shall begin with a copyright notice before any preprocessor directives

Other

• Always provide names of parameters within method declarations, except when hiding constructors
• Always provide explicit return types within method declarations
• Always use a typedef for function pointer types, wrapping std::function as needed
• Never use goto statements (except possibly in a complicated switch)
• Always provide a default case label for switch statements
  • Do not use break in a default case label
• Avoid the use of do-while loops, it is functionally possible to never use them
• Never use literal values at all, always use properly named constants
  • Use nullptr for pointers, not NULL