Coding style

The following are guidelines for the code formatting to use in Code::Blocks source code. Anyone writing code or a patch for Code::Blocks, is required to follow these.

General coding style

The general coding style is the ANSI one:

Example:

namespace FooSpace
{
    int Foo()
    {
        if (isBar)
        {
            Bar();
            return 1;
        }
        else
            return 0;
    }
}

Variables naming

Class names do not start with 'C' (as in CObject, CWindow, etc). Only abstract base classes (interfaces) should start with 'I'. But they all have to start with a capital letter.

Class member variables should start with m_. If the variable is a pointer, use m_p as a prefix. Following the prefix is the variable's name. Use descriptive names and use capital letters at the start of each word (the first too). So a fictious variable holding a value for position would be named as m_ValueForPosition.

Non-class member variables should not start with a capital letter.

Function names should always start with a capital letter.

Examples:

// Good
int aLocalVar;
int m_SomeInt;
void* m_pSomePointer;
bool SomeFunc();

// Bad
int SomeInt; // either no m_ prefix if it's a class variable, 
             // or capital first letter if it's a local variable
int m_someInt; // no capital letter 'S'
void* m_SomePointer; // no m_p prefix
bool someFunc(); // function with non-capital first letter

Parameters that are not absolutely required to be used in an interface or base class should preferrably be tagged with the cb_optional macro so users of the interface realize this, and as a side effect no compiler warnings are generated.

Parameters that are actually not used should be tagged cb_unused both to suppress a compiler warning and indicate that this is happening intentionally.

If the caller of a function takes ownership of the object referenced by the return value, tag the function as cb_must_consume_result.

Variables declaration

One variable declared each time on a different line. For pointer/reference variables, the '*' or '&' is part of the type.

Examples:

// Good
int& someInt;
void* pPtr;

// Bad
int &someInt; // & not after type
void* pPtr, pSomeOther; // multiple declarations in one line

Spacing

Prefer spaces over tabs. If you want to use tabs you won't be prosecuted (!) but please use a tab size of 4 spaces.
Code indentation should be 4 spaces.
In class declarations, the keywords public:, protected:, and private: should be indented. The same goes for all the class members.

Examples:

// Good
class AClass
{
    public:
        AClass(){ ... }
    protected:
        int m_Member;
};

// Bad
class AClass
{
public:
    AClass(){ ... }
protected:
    int m_Member;
};

Commenting

• All three types of comments are used in Code::Blocks. C++ style ('//'), C style ('/* */'), and the Doxygen style ('/** */').
• The C++ style is used for just about everything. Use this style to describe what your code does.
• The C style is used only for very long comments (paragraphs), or for a license or description at the top of a C++ file.
• The Doxygen style is used for documenting functions only. These functions would be public, and protected class functions, and global helper functions.
• Comments should clearly describe what the code does. Comments should be concise, but coherent.

Doxygen style comments

This is the recommended Doxygen style, see [/index.php/topic,15948.msg107431.html#msg107431 comment style question] for details.

/** Short description
 * 
 * Long description
 */

Header file include and Precompiled header rule

The NON-PCH compilation (I mean with NOPCH switch, that's different from simply disabling PCH!) will be helpful to detect missing includes. Keep in mind that no matter what we do - wx will do and use PCH unless we declare NOPCH at the compile time. So even if we disable our PCH, the patches won't stop unless we do it properly in the first place.

The rules are plain simple: PCH file: - include all rarely changing header files - do the PCH macro vodoo (we have that already) Header: - If you access or define an object, include the header - If you use pointers/references, use forward decl - Put headers you need to include into such a section if they are part of your PCH file: Code:

#ifndef USE_PCH
  #include <wx/dialog.h>
#endif

- Include headers you need to include that are not part of your PCH file as normal Implementation: - include the PCH file first - same thing for headers needed as in the header file.

I do it that way in my own projects and i works flawlessly for ages! Of course, whenever I change code and use new classes, I need to check the above rules.

But (nevermind) if we decide to get rid of this because these rules are too hard - go ahead.

Here comes a simple small class: Header:

#ifndef USE_PCH
  #include <wx/dialog.h> // is in wx_pch.h!
#endif

#include <wx/busyinfo.h> // NOT in wx_pch.h and used as object

class MyClass; // forward decsl due to pointer usage

class MyDlg: public wxDialog
{
  MyDlg() { ; };
  void Func(MyClass* c); // used as pointer
  wxBusyInfo bi; // used as object
}

Implementation:

#include <wx_pch.h> // our PCH file, may include the WX PCH file (if needed)

#include "MyDlg.h"

#ifndef USE_PCH
  #include "MyClass.h" // is in wx_pch.h, but now used as object / accessed
#endif

#include "MyOhterClass.h" // NOT in wx_pch.h and used as object

void MyDlg::Func(MyClass* c)
{
  MyOtherClass moc;
  c->DoSomething(moc);
}

See some disscussion in our forum: Morten's comments on include file rules

Also: include rules (by killerbot)