Coding Convention & Style Guidelines


File Naming:

    Back to Top
  1. There will be NO spaces in any filenames or directories.
  2. Right:


    / AIAHealSupport / AIAHealSupport.cpp

    Wrong:


    / HealSupport Template class / AI AHeal Support.cpp

Formatting:

    Back to Top
  1. Use spaces, not tabs. Tabs should only appear in files that require them for semantic meaning, like Make files.
  2. The indent size is 3 spaces.
  3. Right:

    int main()
    {
       return 0;
    }
    

    Wrong:

    int main() 
    {
           return 0;
    }
    
  4. In a header, code inside a class should be indented.
  5. keywords such as public, private, protected and friend should also be indented.
  6. A single blank line should be placed after those keywords.
  7. Any friend keywords should appear at the bottom of a class definition below any other code.
  8. Right:

       class CDocumention
       {
          public:
    
             Document();
             ...
    
          friend class CEffectList;
    
       };
    

    Wrong:

       class CDocumention
       {
       friend class CEffectList;
       public:
       Document();
       ...
       };
    
  9. In a header (.hpp, .h) file, code inside a namespace should be indented.
  10. Right:

       namespace Whiptail
       {
          class CDocumention
          {
             public:
    
                Document();
          };
       };
    

    Wrong:

       namespace Whiptail
       {
       class CDocumention
       {
       public:
          Document();
       };
       };
    
  11. In an implementation (.cpp, .c) file, code inside a namespace should not be indented.
  12. Right:

    namespace Whiptail
    {
    
    CDocumention::Document()
    {
    }
    
    };
    

    Wrong:

    namespace Whiptail
    {
    
       CDocumention::Document()
       {
       }
    
    };
    
  13. A case label should be indented from its switch statement.
  14. A case statement's contents are indented from the case.
  15. The colon after a case statement should have no spaces before or after it.
  16. Right:

    switch (condition)
    {
       case mostLikelyCondition:
       case leastLikelyCondition:
          i++;
          break;
       default:
          i--;
    }
    

    Wrong:

    switch (condition) {
       case leastLikelyCondition:
       case mostLikelyCondition:
          i++;
          break;
       default:
          i--;
    }
    
  17. Use parenthesis in complex mathmatical formulae and expressions.
  18. It is important to make it easy for future readers of this code to visualize and modify order of operations.
  19. Right:

    pfloat32 myValue = (pV0->vx * w0) + ( pV1->vx * w1) + (pV2->vx * w2) + (pV3->vx * w3);
    

    Wrong:

    pfloat32 myValue = pV0->vx * w0 + pV1->vx * w1 + pV2->vx * w2 + pV3->vx * w3;
    
  20. Use parenthesis in complex logic and conditional expressions.
  21. It is important to make it easy for future readers of this code to visualize and modify order of operations.
  22. Right:

    if ((pAudio->pBuffer[0] == 'R') && (pAudio->pBuffer[1] == 'I') && (pAudio->pBuffer[2] == 'F') && (pAudio->pBuffer[3] == 'F'))
    

    Wrong:

    if (pAudio->pBuffer[0] == 'R' && pAudio->pBuffer[1] == 'I' && pAudio->pBuffer[2] == 'F' && pAudio->pBuffer[3] == 'F')
    

Spacing:

    Back to Top
  1. Do not place spaces around unary operators.
  2. Right:

    i++;
    

    Wrong:

    i ++;
    
  3. Do place spaces around binary operators
  4. Right:

    y = m * x + b / n;
    f(a, b);
    c = a | b;
    

    Wrong:

    y=m*x+b/n;
    f(a,b);
    c = a|b;
    
  5. Do place spaces around ternary operators
  6. Right:

    return condition ? 1 : 0;
    

    Wrong:

    return condition ? 1:0;
    
  7. Do Place spaces between control statements and their parentheses.
  8. Right:

    if (condition)
    

    Wrong:

    if(condition)
    
  9. Do Place spaces between each of a functions parameters.
  10. Right:

    f(a, b, c, d);
    

    Wrong:

    f(a,b,c,d);
    
  11. Do not place spaces between a function and its parentheses, or between a parenthesis and its content.
  12. Right:

    f(a, b);
    

    Wrong:

    f (a, b);
    f( a, b );
    

Line breaking:

    Back to Top
  1. Each statement should get its own line.
  2. Right:

    x++;
    y++;
    if (condition)
    {
       DoSomething();
    }
    

    Wrong:

    x++; y++;
    if (condition) DoSomething();
    
  3. An else statement should go on it's own line separate from closing and opening braces.
  4. Right:

    if (condition)
    {
        ...
    }
    else
    {
        ...
    }
    

    Wrong:

    if (condition) {
        ...
    }
    else {
        ...
    }
    
  5. An else if statement should be written as an if statement when the prior if concludes with a return statement.
  6. Right:

    if (condition)
    {
        ...
        return someValue;
    }
    if (condition)
    {
        ...
    }
    

    Wrong:

    if (condition) {
       ...
        return someValue;
    } else if (condition) {
       ...
    }
    

Braces

    Back to Top
  1. Function definitions should have each brace on its own line.
  2. Right:

    int main()
    {
       ...
    }
    

    Wrong:

    int main() {
       ...
    }
    
  3. Class definitions should have each brace on its own line and the final brace should be followed by a semicolon.
  4. Right:

    class CDocumentation
    {
       ...
    };
    

    Wrong:

    class CDocumentation {
       ...
    }
    
  5. Namespaces should have each brace on its own line and the final brace should be followed by a semicolon.
  6. Right:

    Namespace Whiptail
    {
       ...
    };
    

    Wrong:

    Namespace Whiptail {
       ...
    }
    
  7. One-line control clauses should use braces
  8. Right:

    if (condition)
    {
       DoSomething();
    }
    

    Wrong:

    if (condition)
       DoSomething();
    
  9. Control clauses without a body should be avoided but when used should use an empty set of braces and not a trailing semicolon.
  10. Right:

    for (; current; current = current->next) { }
    

    Wrong:

    for (; current; current = current->next);
    

Types & Values:

    Back to Top
  1. The null pointer value should be written as NULL.
  2. CWEntity* pEntity;

    Right:

    pEntity = NULL;

    Wrong:

    pEntity = 0;
  3. bool values should be written as true and false.
  4. bool isValid;

    Right:

    isValid = true;

    Wrong:

    isValid = 1;
  5. Do not use the Objective-C style BOOL type.
  6. Right:

    bool isValid;

    Wrong:

    BOOL isValid;
  7. Tests for true/false and zero/non-zero should all be done without equality comparisons.
  8. Right:

    if (bCondition)

    Wrong:

    if (bCondition == true)
  9. Do not add explicit initializations to temporary variables if you assign to them before testing their value.
  10. Right:

    bool bTest;
    ...
    bTest = GetStatus();
    

    Wrong:

    bool bTest = true;
    ...
    bTest = GetStatus();
    
  11. These are the only allowed 8 bit types used in runtime structures, as data members and in code.
  12. Right:

    char               variableName;
    signed char        variableName;
    unsigned char      variableName;
    

    Wrong:

    UCHAR              variableName;
    
  13. These are the only allowed 16 bit types used in runtime structures, as data members and in code.
  14. Right:

    short              variableName;
    unsigned short     variableName;
    

    Wrong:

    SHORT              variableName;
    USHORT             variableName;
    WORD               variableName;
    
  15. These are the only allowed 32 bit types used in runtime structures, as data members and in code.
  16. bool is a special case it can be used in runtime code but not in structures and not as a data member.
  17. pfloat32 is an internal type which can be a float or a fixed point float.
  18. Right:

    int                variableName;
    unsigned int       variableName;
    float              variableName;
    pfloat32           variableName;
    

    Wrong:

    long               variableName;
    unsigned long      variableName;
    DWORD              variableName;
    ULONG              variableName;
    UINT               variableName;
    INT                variableName;
    FLOAT              variableName;
    BOOL               variableName;
    
  19. These are the only allowed 64 bit types used in runtime structures, as data members and in code.
  20. Right:

    double             variableName;
    sint64             variableName;
    uint64             variableName;
    

    Wrong:

    long long          variableName;
    unsigned long long variableName;
    LONGLONG           variableName;
    LDOUBLE            variableName;
    
  21. These are the only allowed 128 bit types used in runtime structures, as data members and in code.
  22. 128bit values can be used on any cpu that supports sse
  23. Right:

    sint128            variableName;
    uint128            variableName;
    

    Wrong:

    __m128             variableName;
    
  24. These are the only allowed types used in load time structures, as data members and in code.
  25. Right:

    char               variableName;
    unsigned char      variableName;
    short              variableName;
    unsigned short     variableName;
    int                variableName;
    unsigned int       variableName;
    float              variableName;
    

    Wrong:

    signed char        variableName;
    pfloat32           variableName;
    double             variableName;
    sint64             variableName;
    uint64             variableName;
    sint128            variableName;
    uint128            variableName;
    

Names:

    Back to Top
  1. Use lowerCamelCase for variables and data members.
  2. Use CamelCase for a class, struct, protocol, function, method or namespace names.
  3. Fully capitalize acronyms.
  4. Do not use underscores unless specified by another guideline
  5. Right:

    class CDocument;
    struct Data;
    size_t bufferSize;
    char characterDelimiter;
    

    Wrong:

    class documentation;
    class document;
    struct data;
    size_t buffer_size;
    char Characterdelimiter;
    
  6. Engine classes should be preceded by CW, classes outside of the engine are preceded with C
  7. Right:

    class CWDocumentation;
    class CDocument;
    

    Wrong:

    class documentation;
    class document;
    
  8. Engine structs should be preceded by SW, structs outside of the engine are preceded with S
  9. Right:

    struct SWTextureheader;
    struct STexture;
    

    Wrong:

    struct textureHeader;
    struct texture;
    
  10. Prefix class and struct data members with "m_".
  11. Right:

    class CWString
    {
        ...
        short m_length;
    };
    

    Wrong:

    class CWString
    {
        ...
        short length;
    };
    
  12. Precede boolean values with words like "is", "has" and "did".
  13. Right:

    bool isValid;
    bool didSendData;
    bool hasChildren;
    

    Wrong:

    bool valid;
    bool sentData;
    bool children;
    
  14. Use full words, for all variables except in the rare cases where an abbreviation would be more canonical and easier to understand.
  15. Right:

    size_t charSize;
    size_t length;
    short tabIndex;
    

    Wrong:

    size_t characterSize;
    size_t len;
    short tabulationIndex;
    
  16. Avoid using cross meaning iterator variable names in loops, for example do not use i,j or k as iterator variables when working on a Quaternion or x,y and z when working with a vector as these types can contain data members of the same names causing confusion.
  17. Use descriptive verbs in function names.
  18. Right:

    bool convertToASCII(short*, size_t);
    

    Wrong:

    bool toASCII(short*, size_t);
    
  19. Leave meaningless variable names out of function declarations.
  20. Right:

    void SetCount(size_t);
    

    Wrong:

    void SetCount(size_t count);
    
  21. Comment unused variable names out of function definitions.
  22. Right:

    void CWHeap::Free(void* /*pAddr*/)
    {
    }
    

    Wrong:

    void CWHeap::Free(void* pAddr)
    {
    }
    
  23. Use bare words for accessors and should match the name of the variable being accessed.
  24. Right:

    size_t Count();
    

    Wrong:

    size_t GetCount();
    
  25. Precede mutators with the word "set" and should match the name of the variable being accessed.
  26. Right:

    void SetCount(size_t);
    

    Wrong:

    void count(size_t);
    
  27. Engine Enums should be preceded by EW, enums outside of the engine are preceded with E
  28. Enum members should use all uppercase names with words separated by underscores.
  29. Right:

    enum EWMatrixMode
    {
       MM_NONE,
       LOCAL_WORLD,
       CAMERA_VIEW
    };
    

    Wrong:

    enum matrixMode
    {
       None,
       LocalWorld,
       Camera_View
    };
    
  30. #defined constants should use all uppercase names with words separated by underscores.
  31. Right:

    #define KEY_ALT_MASK 0x04
    

    Wrong:

    #define KeyAltMask 0x04
    
  32. Macros that expand to function calls or other non-constant computation. These should be named like functions, and should have parentheses at the end, even if they take no arguments (with the exception of some special macros like STD_ASSERT). Note that usually it is preferable to use an inline function in such cases instead of a macro.
  33. Right:

    #define WBStopButtonTitle()  NSLocalizedString(@"Stop", @"Stop button title")
    

    Wrong:

    #define WB_STOP_BUTTON_TITLE  NSLocalizedString(@"Stop", @"Stop button title")
    
    #define WBStopButtontitle  NSLocalizedString(@"Stop", @"Stop button title")
    
  34. #ifndef, #define "header guards" should be named as _INCLUDED_ then followed by text matching the file name exactly, replacing the '.' with a '_' and capitalizing the text.
  35. Right:

    #ifndef _INCLUDED_MDXTEXTURE_H
    #define _INCLUDED_MDXTEXTURE_H
    

    Wrong:

    #ifndef _MDXTexture_H_
    #define _MDXTexture_H_
    
  36. The #endif for the header guard at the end of the header file should have a double slash comment appended after it showing the macro name
  37. The line above the header guard endif should be the standard seperator comment.
  38. This closing comment should have a space before and after the comment double slash.
  39. Right:

    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    #endif // _INCLUDED_MDXTEXTURE_H
    

    Wrong:

    #endif
    

Other Punctuation:

    Back to Top
  1. Constructors for classes should initialize all of their members using C++ initializer syntax.
  2. All superclasses should be on the same line as the class name
  3. If there are superclasses (parent classes) Starting on the next line after the class name and superclass list each member with its initialization wrapping at less than or equel to 120 characters further members should be initialized starting with an indent one level past the class name.
  4. If there are no superclasses (parent classes) Starting on the same line as the class name each member should be initialized wrapping at less than or equel to 120 characters then further lines of members are indented one level past the class name.
  5. If there are are so few members and superclasses that the initialization fits under 120 characters Starting on the same line as the class name each member should be initialized.
  6. There should be more than one member on each line making it as compact as is readable without exceeding 120 characters per line including indentation
  7. The initializer list should match the order of class data members precisely
  8. Right:

    Documentation::Documentation(Document* pDoc) : XMLReader(), XMLWriter(),
       m_memberAlpha(0), m_memberBeta(0), m_memberGamma(0),
       m_memberDelta(0), m_memberEpsilon(0), m_memberZeta(0),
    {
    
    };
    
    XMLReader::XMLReader() : m_memberAlpha(0), m_memberBeta(0), m_memberGamma(0),
       m_memberDelta(0), m_memberEpsilon(0), m_memberZeta(0),
    {
    
    };
    
    XMLWriter::XMLWriter() : FileIO(), m_memberAlpha(0)
    {
    
    };
    

    Wrong:

    Documentation::Documentation(Document* pDoc) : XMLReader(), XMLWriter()
    {
       m_memberAlpha = 0;
       m_memberBeta = 0;
       m_memberGamma = 0;
       m_memberDelta = 0;
       m_memberEpsilon = 0;
       m_memberZeta = 0;
    }
    
  9. Pointer and reference types are compound types and should be written with no space between the type name and the * or & followed by spaces and or indents then the variable name.
  10. Right:

    Image* TextureHandler::DoSomething(Color& tint)
    {
       Color* pElement = static_cast<Color*>(node());
       const ColorArray& colors = ColorInputs();
    

    Wrong:

    Image *TextureHandler::DoSomething(Color &tint)
    {
       Color *element = static_cast<Color *>(node());
       const ColorArray &colors = ColorInputs();
    
  11. Prefer const to #define.
  12. Prefer inline functions to macros.
  13. Inline functions should be explicitly marked as inline with the inline keyword.
  14. Right:

       inline Color* GetColor() { return m_pColor; }
    

    Wrong:

       Color* GetColor() { return m_color; }
    
  15. Inline functions consisting of one call or operation should occupy no more than 1 line of code and coexist inside the class definition.
  16. Right:

       inline Color* GetColor() { return m_pColor; }
    

    Wrong:

       inline Color* GetColor()
       {
          return m_color;
       }
    
  17. Inline functions that consist of more than one call or operation should be prototyped (declared) in the class definition and implementated (defined) in the same header after the class defenition.
  18. Both the prototype (declaration) and the implementation (definition) of inline functions should have the inline keyword as some compilers use one or the other or both to determine inlining rules.
  19. Implementing intentional infinite loops should be done with a for(;;).
  20. Right:

    for (;;)
    {
       ...
    }
    

    Wrong:

    while (true)
    {
       ...
    }
    while (1)
    {
       ...
    }
    
  21. Enumerations should always be named so they can be used as type safe parameters.
  22. Right:

    enum EWTypes
    {
       ...
    }
    

    Wrong:

    enum
    {
       ...
    }
    
  23. If the object you are calling a function on, is not going to be modified durring the functions scope, the function should ALWAYS have the const modifier on the end.
  24. Right:

    unsigned int GetSize() const { return m_size; }
    
    unsigned int SetSize(unsigned int size) { m_size = size; }
    

    Wrong:

    unsigned int GetSize() { return m_size; }
    
    unsigned SetSize(unsigned int size) const { m_size = size; }
    
  25. When passing pointers or references to items as function paramaters, and the item being passed should not change, you should mark the parameter as const.
  26. Right:

    void Print(const char* pString); // pString is not modified
    
    void ModifyString(char* pString); // pString may be modified
    
    void ScanObject(const CObject& obj); // obj is not modified
    
    void ModifyObject(CObject& obj); // obj may be modified
    

    Wrong:

    void Print(char* pString);
    
    void ModifyString(const char* pString);
    
    void ScanObject(CObject& obj)
    
    void ModifyObject(const CObject& obj);
    
  27. There is some times confusion on where the const modifier goes when passing parameters, if you dont want the parameter being pointed/referenced to be modifiable do this.
  28. Right:

    const CObject* pObj
    

    Wrong:

    CObject* const pObj
    
  29. If however you do not care if the object being pointed to is modifiable, but want to verify the pointer itself never changes, you do the opposite.
  30. Right:

    CObject* const pObj
    

    Wrong:

    const CObject* pObj
    
  31. Structs cannot have any member functions they are reserved for data members only.
  32. Right:

    struct SWEntityData
    {
       unsigned int m_id;   ///< Comment
       unsigned int m_info; ///< Comment
    }
    

    Wrong:

    struct SWEntityData
    {
       unsigned int m_id;   ///< Comment
       unsigned int m_info; ///< Comment
    
       /// Get ID
       unsigned int GetID() { return m_id; }
    
       /// Set ID
       void SetID(unsigned int id) { m_id = id; }
    }
    

Include Statements

    Back to Top
  1. All cpp files must #include "mstdinc.h" first before all other headers.
  2. All cpp files must #include their primary header second, just after "mstdinc.h".
  3. All subsequent #include statements should be in sorted alphanumeric logical order
  4. Right:

    #include "mstdinc.h"
    #include "thisimplementation.h"
    #include "alpha.h"
    #include "beta.h"
    

    Wrong:

    #include "thisimplementation.h"
    #include "alpha.h"
    #include "mstdinc.h"
    #include "beta.h"
    

Asserts and Logging

    Back to Top
  1. Use STD_ASSERT macro to assert on all platforms.
  2. Right:

    STD_ASSERT(pEntity);
    

    Wrong:

    assert(pEntity);
    
  3. Use STD_LOG to write to the log file.
  4. Use STD_VERBOSE for SPAMMY console output.
  5. Use STD_TRACE for non-spammy INFORMATION output.
  6. Use STD_WARNING for NON-CRITICAL ERRORS.
  7. Use STD_ERROR for CRITICAL ERRORS.
  8. Right:

    for (;;)
    {
       STD_VERBOSE("Spam I am\n");
    }
    

    Wrong:

    for (;;)
    {
       STD_TRACE("Spam I am");
    }
    
  9. You must include your own newlines ('\n') in all logging and console output commands.
  10. Right:

    STD_LOG("Complete line of output\n");
    

    Wrong:

    STD_LOG("Complete line of output");
    

Memory Management

    Back to Top
  1. Avoid excessive temporary heap allocations. Utilize stack memory and heap pools.
  2. Right:

    char sName[32];
    for (;;)
    {
       GetName(sName);
       UseName(sName);
    }
    

    Wrong:

    for (;;)
    {
       char *sName;
       sName = new char[32];
       GetName(sName);
       UseName(sName);
       delete [] sName;
    }
    
  3. When using the array delete operator place a space between the delete keyword and the square brackets.
  4. Right:

       delete [] pData;
    

    Wrong:

       delete[] pData;
    
  5. When in platform independant code (code common to all platforms) use WMemSet(), WMemCopy(), WMemMove() functions in place of platform versions.
  6. Right:

       /// Common code across all platforms
       WMemSet(pAddress, 0, sizeof(object));
    

    Wrong:

       /// Common code across all platforms
       xmemset(pAddress, 0, sizeof(object));
    
  7. In platform Dependant code (code specific to one platforms) use memset, memcopy, memmove functions designed for that specific platform.
  8. Right:

       /// DirectX Win32
       memset(pAddress, 0, sizeof(object));
    

    Wrong:

       /// DirectX Win32
       WMemSet(pAddress, 0, sizeof(object));
    
  9. Make sure your new and delete operator types match up, if you new as an array delete as an array.
  10. Right:

       m_pCurves = new CWAnimCurve[m_nCurves];
       ...
       delete [] m_pCurves;
       ...
       m_pCurve = new CWAnimCurve();
       ...
       delete m_pCurve;
    

    Wrong:

       m_pCurves = new CWAnimCurve[m_nCurves];
       ...
       delete m_pCurves;
       ...
       m_pCurve = new CWAnimCurve();
       ...
       delete [] m_pCurve;
    

Patch Creation - Tortoise

    Back to Top
  1. Using Tortoise to create a patch
  2. The correct way :

    
    

    Wrong:

    // ma codes here
    codes
    codes
    

Patch submission - Via the forums

    Back to Top
  1. Submitting your patch via the forums
  2. The correct way :

    Patch Title:
    
    What bug does this patch fix:
    
    Detailed Explanation:
    
    How to reproduce:
    Link to thread in bug reports section if available:
    
    Patch:
    Wrap your patch in
    [code][/code]
    tags.
    As well, please upload the .patch file
    

    Wrong:

    Hunter pet level patch!
    
    //Pet.cpp
    CODE
    // Hunter pet should be max 5 levels below owner
        uint32 level = owner->GetUInt32Value( UNIT_FIELD_LEVEL );
        if( type & 0x2 && created_from_creature != NULL )
            level = created_from_creature->getLevel() < ( level - 5 ) ? level - 5 : created_from_creature->getLevel();
    

Comments

    Back to Top
  1. The standard seperator is 120 slash characters.
  2. Right:

    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    

    Wrong:

    //\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//
    //----------------------------
    //***********************************************************
    
  3. Functions should be separated by TWO empty lines.
  4. Right:

    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    bool ReturnTrue()
    {
       return true;
    }
    
    
    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    /// Next function description
    

    Wrong:

    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    bool ReturnTrue()
    {
       return true;
    }
    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    /// Next function description
    

Doxygen

    Back to Top
  1. All source files will have a doxygen header.
  2. For header files, this should immediately follow the HEADER GUARD.
    Sample Header
  3. Right:

    #ifndef _INCLUDED_SOURCE_H
    #define _INCLUDED_SOURCE_H
    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    //
    // Copyright (c) Barking Lizards Technologies LLC, 2008, 2009
    // All rights reserved.
    //
    // Filename: source.h
    //
    // Description: Overview of the code included in this file
    //
    // Original Author:  Firstname 'Nickname or username' Lastname
    //
    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    

    Wrong:

    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    // Overview of the code included in this file
    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    #ifndef _INCLUDED_SOURCE_H
    #define _INCLUDED_SOURCE_H
    
  4. For source files, this should be at the top of the file.
    Sample Source File
  5. Right:

    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    //
    // Copyright Barking Lizards Technologies LLC, 2008, 2009
    // All rights reserved.
    //
    // Module Name: source.cpp
    //
    // Description: Overview of the code included in this file.
    //
    // Original Author: Firstname 'Nickname or username' Lastname
    //
    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    

    Wrong:

    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    // Overview of the code included in this file
    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    
  6. The comments for function declarations should be brief and only use one line, use three slashes and a space, and come one line before the function declaration.
  7. Right:

    /// Create entity and add it to the world
    static EWResult Add( const char* pEntFile, const char* pEntName=0, const char* pSpawnPoint=0 );
    

    Wrong:

    //Create entity from .ENT file specified and then add it to the world.  If pEntName!=0,
    //use that as the entity's unique name.  If pSpawnPoint!=0, position the entity there.
    static EWResult Add( const char* pEntFile, const char* pEntName=0, const char* pSpawnPoint=0 );
    
  8. The function definition/implementation should have a more detailed description and should be formatted in doxygen triple slash C++ special block style
  9. Functions should be commented above their definition/implementation and not below it.
  10. There are no newlines between a functions documentation block and the function itself.
  11. A function comment block consists of a leading and trailing seperator line.
  12. Lines between the seperators are commented with a triple slashe per line.
  13. Right:

    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    ///
    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    bool ReturnTrue()
    {
       return true;
    }
    

    Wrong:

    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    //
    //
    bool ReturnTrue()
    {
       return true;
    }
    
  14. Function comment blocks begin with a semi brief sometimes multiple line description.
  15. All parameters to the function must be commented with a \param section.
  16. Return values must be commented with a \return section.
  17. Do not add a return section if it will be void.
  18. If a function would benefit from it point to other functions or classes with a \sa which means see also.
  19. Any unfinished functionality should be docmented with a \todo section.
  20. Any very detailed information or things other programmers should know when using this code should go in a \note section.
  21. Do not add any section if it will be empty.
  22. Right:

    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    /// Create entity from .ENT file specified and then add it to the world.
    ///
    /// \param  pEntFile    -- ENT Filename
    /// \param  pEntName    -- (optional) Unique name for entity instance
    /// \param  pSpawnPoint -- (optional) Entity name to use as spawnpoint
    ///
    /// \return RES_FILE_NOT_FOUND if ENT file missing. RES_FAILURE if CreateEntity fails, otherwise RES_SUCCESS
    ///
    /// \note If pEntName != 0, use that as the entity's unique name.
    ///       If pSpawnPoint != 0, position the entity there.
    ///
    /// \sa CWEntity::Remove()
    /// \sa CWEntity::Delete()
    ///
    /// \todo Add more error codes for return values
    /// 
    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    EWResult CWEntity::Add(const char* pEntFile, const char* pEntName, const char* pSpawnPoint)
    

    Wrong:

    // Create entity from .ENT file specified and then add it to the world.
    EWResult CWEntity::Add(const char* pEntFile, const char* pEntName, const char* pSpawnPoint)
    
  23. The comment blocks for class declarations should be detailed, use three slashes and a space, and come one line before the class declaration.
  24. The first line of the comment block should be a \class section.
  25. The next line of the comment block should be a \brief section followed by an empty line with just a triple slash.
  26. This is followed by a detailed description of the class and if required a \note block to cover any thing code maintainers may need to know.
  27. Right:

    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    /// \class CWTimeManager
    /// \brief Provides an interface to timing related functions.
    ///
    /// Provides an interface to timing related functions that are used to uniformly control the
    /// progression of time throughout the engine. Custom timers can be created or the built in timers that optionally
    /// reflect pause state can be used. Custom timers support optional pause state and multiplier.
    /// Built in timers are automatically updated by the engine and should not have settings modified.
    ///
    /// \note This is the base class platform dependant classes derive from this
    ///
    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    class CWTimeManager
    

    Wrong:

    // CWTimeManager Provides an interface to timing related functions.
    class CWTimeManager
    
  28. You cannot place a comment at the end of a line.
  29. Right:

       /// Increment our counter
       ++j;
    

    Wrong:

       ++j; /// Increment our counter
    
  30. Class member variable descriptions should be on the same line as the variable after the semi colon and be formatted as a triple slash followed by less than symbol and a space before the comment.
  31. Right:

    CWEntitySet        m_entities;           ///< Main entity list
    

    Wrong:

    //Main entity list
    CWEntitySet        m_entities;
    

Subversion

    Back to Top
  1. All subversion commits should have clear descriptions of what changed and why.
  2. Right:

    ADDED : new base class function EndBracket()
    CHANGED : layout of base class declarations
    ADDED : DirectX implementation of EndBracket()
    REMOVED : Old DirectX implementation of End()
    UPDATED : commented depreciated unused members
    FIXED : Bug in rotation of matricies
    

    Wrong:

    I changed some stuff
    
  3. Take advantage of atomic commits. Commit all files that have inter-dependent changes at once.
  4. When commenting a commit of multiple files, list each file or group of files and the changes made to each.
  5. Right:

    mwgraphicscore.cpp/h: ADDED : new base class function StartBrackets()
    mwdxgraphicscore.cpp/h: ADDED : DirectX implementation of StartBrackets()
    

    Wrong:

    I changed some stuff, and added a few things
    

Projects

    Back to Top
  1. Sample Visual Studio 2008 project file
  2. General
  3. Debug:

    Release:

  4. C++ General
  5. Debug:

    Release:

  6. C++ Optimization
  7. Debug:

    Release:

  8. The following standard preprocessor defines should take place before any game/whiptail side defines
  9. Debug:

    WIN32  _WIN32  WINDOWS  _WINDOWS  DEBUG  _DEBUG

    Release:

    WIN32  _WIN32  WINDOWS  _WINDOWS  NDEBUG  _NDEBUG
  10. C++ Preprocessor
  11. Debug:

    Release:

  12. C++ Code Generation
  13. Debug:

    Release:

  14. C++ Language
  15. Debug:

    Release:

  16. C++ Precompiled Headers
  17. Debug:

    Release:

  18. C++ Output Files
  19. Debug:

    Release:

  20. C++ Advanced
  21. Debug:

    Release: