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. Therefore these 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.

Typedefs

Using the typedef keyword can improve readability and save typing by providing a simple name for a more complex data structure, however inappropriate use can also reduce readibility by forcing the reader to look up numerous typedefs which do no more than rename a standard type.

For example:

typedef std::vector<std::string> StringList

is a good typedef, because it is obvious what the type means, it allows easy editing if it were required to change it to a std::list rather than a vector (for example), and it makes it easy to work with derived types (StringList::iterator rather than std::vector<std::string>::iterator).

On the other hand,

typedef float ShaderScaleParameter

is a bad typedef. It provides no improved readability over simply using the primitive type, and gives the impression to a reader unfamiliar with the code that a more complex data structure is being used.

• Always name typedefs based on what the type is, not what it is for. Use "StringList" rather than "ShaderParameterList" or "ArgumentList".
• Never use typedefs to rename a standard type (unless there is a specific purpose, like providing a standard public typedef as part of a functor interface).

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 for string variables, 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.

Data allocation

Use boost::shared_ptrs wherever you need to allocate objects on the heap, as these objects auto-destruct when the last ptr instance is destroyed. Use new only if you need tight control of when the object should be removed from the heap, or to instantiate GUI classes that auto-destruct in their callbacks.

A shared ptr should be named like this (Ptr suffix):

typedef boost::shared_ptr<MyClass> MyClassPtr;

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.).