DarkRadiant coding standards

Although DarkRadiant was forked from GTKRadiant, the style of legacy GTKRadiant code should not be used as an example for new code. There following coding standards should be used for new code, in order to maximise readability for developers.

Naming conventions

• All new code should be in a namespace, such as ui for UI-related code or model for code dealing with models.
• Class names should begin with a capital letter and capitalise each word: RenderablePicoModel, TextMenuItem
• Classes represent "things", therefore they should be named after nouns not verbs: ModuleLoader rather than LoadModule.
• Each new class should be contained within its own file pair: MyClass is contained in MyClass.h and MyClass.cpp. This rule does not apply to tightly-bound local classes, such as a functor class which is used by only a single method in a .cpp file. It is also acceptable to define trivial data structures returned by methods in the header file declaring the method, if that data structure is not used elsewhere.
• Method names and local variables should start with a small letter.
• Member variables should begin with an underscore: _widget. Do not use the "m_name" convention in new code, as this is harder to read.

General code structure

• Always use Object-Oriented design methods wherever possible. Think in terms of objects which define methods to act on those objects, rather than C-style functions that process data structures passed as arguments. Non-member functions are OK for minor tasks, as long as they are within a namespace rather than at global scope.
• Never use global variables.

Data types and objects

• Always use STL or Boost objects, rather than home-grown reinventions of the same thing. Use std::string not CopiedString, and std::map in favour of HashedCache. Classes that use these home-grown versions should be modified so as not to use them if at all possible, and eventually they will be removed.
• Do not use const char* objects except where necessary to pass to a library function (such as the C-based GTK library), or where a string constant is needed. Functions that accept or return strings should use std::string instead.

Static variables

If a static variable is required, encapsulate it within a small method that returns a reference to the static, e.g.

MyObject& staticInstance() {
    static MyObject _instance;
    return _instance;
}

This ensures that the static instance will be initialised when the method is first called, which avoids problems with the undefinability of static initialisation.

Access

• All data members should be private, except in data structures which provide no methods (other than constructors).
• Members which need to be accessed externally should be provided with get/set methods. This is an important part of separating interface from implementation, since a get/set method might actually modify more than one member variable, or even perform a calculation without referencing members at all.

Comments

Exactly where and how to place comments is a matter of personal preference. However, at the very least, all public methods and functions should be commented in their associated header file, with details of their parameters, return value and function, along with any other important information (such as prerequisites for calling the function, who is responsible for destroying returned data etc.).