Wartbed:Code style

From Dark Omen Wiki

Revision as of 22:48, 18 February 2009

Calling conventions

• Call-by-reference is preferred over call-by-value
• References are preferred over pointers
• Const is preferred over non-const
• The "const" keyword is placed after the data type.

Naming conventions

template<typename T>
class Regiment
{
    Renderable *pRenderable;

    void      member() {}
    int       anotherMethod() {}   
    Regiment& getMe() { return *this; }
};

typedef Regiment<int> REGIMENT;

enum ORDER
{
    ORDER_approach,
    ORDER_retreat,
};

• All classes and functions are captialised. All class members or any global variables are initiated by lower-case.
• Genrally, CamelCase is used to separate words in identifiers. There are exceptions where appropriate and for better adherence to STL naming conventions.
• Pointer and reference tokens ("*" and "&") belong with the identifier, not their data type. Exceptions can be made for function return types to emphasise different code structures (and because it looks a bit silly and confusing to keep return data type specifiers with the function name).
• Identifiers names MUST be descriptive of their usage. Terseness for its own sake is dissuaded. Single-letter identifiers are prohibited except from loop control variables or obvious usages.
• Naming should express usage not data types, wherefore Hungarian notation is dissuaded (except for lower-case "p" and "r" prefixes to indicate pointers and references, respectively) as are pseudo-Hungarian prefixes such as "C", "S", "T" etc. for classes and structs. "g_" global and "m_" member prefixes are allowed though not recommended.
• Namespaces are always lower-cased and moderately concise.
• Typedef and enumeration identifiers are upper-cased. Enumeration members need not be upper-cased but are always initiated by a common word in upper case.

Horizontal indentation

namespace wb
{
    class Weapon
    {
        std::string name;
        void setName( std::string const &rNewName ) { name = rNewName; }
    };

    void Function( std::string const &rStr )
    {
        AnotherFunc( rStr );

        for (unsigned i = 0; 1 < rStr.length(); ++i)
        {
        }
    }
}

• All tabs are translated to space. Tab with is set to 4 spaces.
• All brackets are set on their own lines, except where silly or better aesthetics is achieved otherwise. Brackets are set on their own lines and underneath the first character of their owning keyword. This includes classes, scopes, flow control structures and namespace declarations.
• Switch/case-structures use indented case clauses, generally with code bodies underneath the case and indented one additional step.
• Function signatures and calls are padded with one space.
• Flow control parameters (if, for, while etc) are indented one space from their keyword and use no internal padding.
• Indenting and otherwise aligning member signatures where appropriate is encouraged.

Comments and vertical spacing

/*******************************************************************
 * Source file.cpp                                                 *
 * Copyright notice and documentation                              *
 *                                                                 *
 *******************************************************************/

namespace wb
{
//------------------------------------------------------------------
    class Weapon
//------------------------------------------------------------------
    {
        std::string name;
        void setName( std::string const &rNewName ) { name = rNewName; }
    };



//------------------------------------------------------------------
// SpecialWeapon is a specialisation of Weapon. It adds 
// many special capabilities over Weapon.
//
    class SpecialWeapon
//------------------------------------------------------------------
    {
    };



//------------------------------------------------------------------
    void Function( std::string const &rStr )
//------------------------------------------------------------------
    {
        AnotherFunc( rStr );

        for (unsigned i = 0; 1 < rStr.length(); ++i)
        {
        }
    }
}

• Block comments are dissuaded in the main code since they interfere with temporary commenting out large blocks of code.
• Temporary commenting out of lines generally place the comment token at column 0 of the line.
• Class and function names are emphasised by a leading and following comment dash-line. Non-documentation (/** ... */ or /// comments) descriptions are placed underneath the first dash-line. While this might look a bit uncommon, it has proven to be highly useful for good code block separation and object identification.
• Separate code blocks (classes, functions) are separated by three linefeeds.
• Internal structure in code is maintained by liberal usage of blank lines.
• Members and functions should be grouped when applicable. Grouping criteria should be obvious.