Skip to content

CodingStandards

Astaelan edited this page Dec 5, 2011 · 3 revisions

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
Clone this wiki locally