Code conventions

Abstract

This document describes the programming style I used while writing the GUI library. I did not write it to talk you or anyone else into using it, but it could come in handy if you're interested in writing your own Components and contributing to the project, although you're of course free to use whatever coding convention you see fit. In the end, I don't really care what you use, as long as you use it consistently.

Language

Only C++ is used for writing this toolkit, no C, C/C++ hybrid, only pure C++. This means all C headers are illegal, and globals are bad. If you must have a global, turn it into a Singleton object. All C++ files end with a .cpp extension and all header files with .h. Also, all class definitions must be contained in header files, and all code related to the implementation must be in a file with the same name and a .cpp extension. Exception to this rule are templates, where implementations go into the header file.

Naming conventions

Classes

Classes should be nouns, with the first character of each noun capitalized. Class names must be simple and descriptive, avoid using abbreviations.

Component
SelectionManager

Functions

Methods should be verbs, with the first character of each word capitalized.

getBorder
validate

Variables

The same rules for methods apply to variables. Make sure every variable is short and descriptive.

selectedComponent
height

Constants

#define is not used, only enumerations. All constants in an enumeration must be capitalized, short and descriptive. The enumeration name itself is also capitalized. “Magic numbers” should be avoided, but if absolutely necessary a static const variable can be used.

enum CONSTANTS
{
    CENTER,
    LEFT,
    RIGHT
};

static const int MAX_PLAYERS = 64;

Casts

I prefer C++ style casts over C casts. Although C++ style casts are more work (you have to type more), they stand out in the code, and show the intention of the code more clearly. For example:

float number = 100.0f;

int result = static_cast<int>(number);

Namespaces

Use namespaces to divide up the global namespace into understandable portions. As a bonus, you no longer have to add prefixes to your class names, for example GUICheckBox becomes:

namespace gui
{
   class CheckBox;
}

If you do not wish to use namespace, simply import the namespaces you need into the local scope with the using namespace <namespace>; directive. Just be sure to never do this in a header file, as it pollutes the global namespace.

Indentation

Tabs are used as indention, not spaces. Avoid using spaces as indention at all costs.

Braces

Braces always appear on a new line, and the indentation of these braces should always match (the opening and closing braces). This means a simple if/else statement looks like this:

if(someCondition)
{
    // do something
}
else
{
    // do something else
}

This also means if/else statements always use braces. Try to avoid using the ternary operator (isTrue ? true : false).

Documentation

Javadoc commenting style is used in header files to document classes, methods and variables. This is done as follows:

/**
 * Short class description.
 * Detailed class description.
 * parameter list
 */

From this, API documentation is generated by Doxygen. For more information on the javadoc commenting style, see the Doxygen manual.

Other forms of comments can be used in .cpp files, as long as they are there to make the code easier to understand.