Coding style

Naming style

Namespaces, classes and structs, enums, type template names and static constants should be named with CamelCase, i.e. first letter of the name and each successive word uppercase, other lowercase. E.g. ConfigurationGroup. Classes with pure virtual methods or base classes which are not meant to be used directly should be prefixed with Abstract.

Functions, function parameters, non-type template names and variables should be named with camelCase, i.e. first letter of the name lowercase, each successive word starting with uppercase. E.g. trimLeadingSpaces().

Preprocessor macros should be written in uppercase with underscores between words, e.g. CORRADE_EXPORT and prefixed with project name. Exceptions are tiny one-shot macros that are #undefined right after they are used (switch case helpers etc.), in that case they are lowercase and prefixed with underscore.

Redundant information and abbrevations in names are not recommended (use determinant, inverse and attribute instead of det, inv and attr). Hungarian notation, I and E prefixes for interfaces and enums are forbidden and cruelly punished, if found. Acronyms should be written with first letter uppercase only to avoid visual collision with preprocessor macros (Http and Sha1 instead of HTTP and SHA1).

Private variables should be prefixed with a single underscore. Don't use the m_ prefix or nothing at all. Don't use two underscores, as they are reserved for internal usage by the C++ standard. Underscores before the name shouldn't be used in public API or function parameters, as it looks ugly in the documentation.

Global and class-static variables shouldn't be used for obvious reasons (static initialization order fiasco, negative effect on startup and shutdown time, thread safety etc.). If there is no other option, try to reduce its scope as much as possible — anonymous namespace or constexpr function-local variable, using CamelCase naming. If the variable is a numberic constant, put it in an typed enum instead. Don't use the g_ prefix.

API usability and naming clarity

Where performance concerns doesn't make it impractical, immutable APIs that return modified data are preferred to APIs that mutate itself. For example, in the following example, the hypothetical matrix class API actually mutates the original instance — similar to GLM's design, in a way:

Matrix 4 a;
a.translate({3.0f, 1.0f, 2.0f});
a.rotate(Deg(35.0));

The reason this is bad is that you need two expressions to create a rotation matrix (first create the instance, then mutate it), or write unintuitive code like Matrix4{}.translate(…). Not to mention issues where it's not clear from which side the transformations get combined. To fix that, with an API written in an immutable design, the above would be instead:

Matrix 4 a =
    Matrix4::rotation(Deg(35.0f))*
    Matrix4::translation({3.0f, 1.0f, 2.0f});

Note the different naming — the functions now say "this is what you get on output" instead of "this is what I will do on the instance", and also note the different order — with the above it had to be assumed (or checked in the docs or source code) that translation happens first and rotation after, with this the order is clearly given by how the matrix multiplication happens.

To prevent mutability/immutability confusion, immutable functions shouldn't use verbs. For example the following Containers::String API existed originally and had to be renamed to avoid confusion:

Containers::String a = "not confused!";

a.stripPrefix("not "); // does nothing -- the function actually returns a view

Now it's Containers::String::exceptSuffix() which makes it clearer that the user gets a result back and nothing is mutated.

Forward declarations and forward declaration headers

Each namespace should have a forward declaration header with forward declarations of types that are often used. The header is named after the namespace and is placed inside the namespace folder, so e.g. namespace Corrade::Utility has src/Corrade/Utility/Utility.h header with forward declarations.

Prefer forward declarations to includes as much as possible, as it significantly reduces compilation time. Apart from class and structure forward declarations, put also relevant typedefs in the forward declaration header and make use of C++11 forward-declared enums.

Namespace declarations

In line with vertical code compression, namespace declaration is on one line, separated with blank lines on both sides, closing brackets being all on the same line. The code inside the declaration is not indented to save horizontal space.

namespace Corrade { namespace Utility { namespace Test {

// ...

}}}

Separate the namespace declarations and indent them only if it improves readability and is not excessive, e.g. in case of internal forward declarations:

namespace Corrade { namespace Utility {
    class Configuration;
}}

namespace Corrade {

namespace TestSuite {
    class Tester;

    namespace Compare {
        class FileContents;
    }
}

// the actual code...

}

Class and structure declarations

Class and structure protection levels are ordered as following: first public members, then protected members and finally private members, so class public interface is easy to spot at the top of the file. Friend declarations are preferred to stay in the private section at the end, as they are usually not very important.

Members are ordered as following: first classes and enums, then static functions, then non-static functions (where constructors, destructors and assignment operators are first), then static variables, then non-static variables. Again, classes and methods are more important for user than variables, static members are more important than non-static.

To avoid accidental implicit forward declaration when declaring friends, use the C++11 friend declaration without class/struct keyword (so friend Bar; instead of friend class Bar;).

Blocks, whitespace and indentation

The goal is to preserve readability with minimal amount of wasted vertical and horizontal space.

Indented is everything except namespace declarations (as specified above) — blocks, class protection levels, case statements. Overlong line breaks are indented also with 4 spaces (or any other value if it makes more sense, e.g. for aligning similar code).

class Foo {
    public:
        void bar() {
            addMethods(&Foo::methodNameOne,
                       &Foo::methodNameTwo);
        }

    protected:
        void methodNameOne();
        void methodNameTwo();
};

Whitespace is not allowed inside parentheses and between function name or branch/loop statement and left parenthesis (or between constructed variable name and left brace) and before semicolon. It must be around block braces if the block is not empty. It must not be space before, but after the comma.

if ( statement&&! other ){foo ( a ,b ) ;}  // awful! (_everything_ is misplaced)
if(statement && !other) { foo(a, b); }     // perfect

Whitespace should be around operators with low precedence (namely +, -, <<, >> but not on unary -), around all boolean and comparison operators (&&, ||, ==, !=, <, <=, >=, >), around = and related operators and around ternary operator. Whitespace shouldn't be around /, *, % to indicate they have precedence before addition and subtraction. Whitespace can or need not to be around binary operators (&, |, ^), whichever looks better in particular content.

a += b*5 - 3*(c != 0 ? 64/c : 1);

In general, an indentation style not dependening on particular naming choices should be preferred to avoid nontrivial editing effort when refactoring later. In case of functions, the argument list is replicated in Doxygen code anyway, which is optimized for readability (see below).

// Bad
void fizzBuzzImplementationV3Final(std::ostream&         out,
                                   const std::string&    fizzTemplate,
                                   const std::string&    buzzTemplate,
                                   Util::LoggerInstance& logger);

// Good
void fizzBuzzImplementationV3Final(std::ostream& out, const std::string& fizzTemplate,
    const std::string& buzzTemplate, Util::LoggerInstance& logger);

Block opening braces start on the same line as corresponding statement (class / function declaration, branch and loop statement), else and else if statements have both braces on the same line too:

if(expression) {
    // ...
} else if(another || expression) {
    // ...
} else {
    // ...
}

If the block is only one statement and short enough (<80 columns), it can be on the same line:

void setProcessingDelay(int delay) { processingDelay = delay; }

if(!initialized) return false;

The only exceptions when opening braces are on the following line is when the if statement or constructor initializer list is spanning multiple lines and the other way would confuse what belongs inside the block and what outside. There you can also indent in a way that aligns similar code.

if(a_very_long_expression_spanning_whole_line ||
   another_fairly_lengthy_expression ||
   yet_another_overly_complicated_expression)
{
    // ...
}

MyClass::MyClass():
    _oneMember{lengthy_member_initialization},
    _anotherMember{another_fairly_lengthy_expression},
    _thirdMember{more_code}
{
    // ...
}

The opening brace should be also on the following line when preprocessor branching is involved, as specifying it twice may confuse code folding in some editors:

// Bad
#ifndef CORRADE_TARGET_WINDOWS
if(expression) {
#else
if(worked || around || expression) {
#endif
    // ...
}

// Good
#ifndef CORRADE_TARGET_WINDOWS
if(expression)
#else
if(worked || around || expression)
#endif
{
    // ...
}

Switch statements

Switch statements are usually very verbose and thus they are often subject of various shortening and whitespace tricks. The goal is to make them as readable as possible without wasting too much vertical space, for example:

switch(type) {
    case Type::Byte:        size = 8;   break;
    case Type::Short:       size = 16;  break;
    case Type::Int:         size = 32;  break;
    case Type::Long:        size = 64;  break;
    case Type::LongLong:    size = 128; break;

    default:                size = 0;
}

In case of longer statements or variable declarations inside switch cases that require a block, the style template is as follows:

switch(event.type()) {
    case EventType::KeyPress:
    case EventType::KeyRelease: {
        KeyEvent e{event.type(), event.key()};
        keyEvent(e);
    } break;

    case EventType::TouchSwipe:
        Debug() << "Unimplemented.";
        break;
}

Most compilers are able to warn if a switch doesn't cover all cases, so make use of that feature — if the switch statements enumerated all possible values of given enum, don't put a default statement with fallback code there because that will silence possible warning if someone adds a new enum value without updating the enums:

// Bad
std::size_t size;
switch(type) {
    case Type::Byte:        size = 8;   break;
    case Type::Short:       size = 16;  break;
    // Type::Int missing but the compiler doesn't warn so it fails at runtime
    case Type::Long:        size = 64;  break;
    case Type::LongLong:    size = 128; break;

    default:
        Error() << "Unknown type";
        size = 0;
}

// Good
std::size_t size = 0;
switch(type) {
    case Type::Byte:        size = 8;   break;
    case Type::Short:       size = 16;  break;
    case Type::Long:        size = 64;  break;
    case Type::LongLong:    size = 128; break;
} // warning: Type::Int not handled in switch statement

if(!size)
    Error() << "Unknown type";

Class member and function keywords

Use keywords in this order: template virtual inline constexpr explicit static. When the function is fully defined in class body or when it is marked as constexpr, don't mark it as inline, it's redundant. Only base virtual functions should have virtual keyword, the reimplementations should be marked with override instead.

Preprocessor macros

Preprocessor macros should have the same indentation as surrounding code. Not indenting or indenting between # and the macro breaks visual flow and thus is not allowed. If the macro is long or contains code which should be spanned or multiple lines, it should be wrapped on multiple lines, each successive line indented and the line wrapping indicator \ should be aligned around 80th column, preferably on some tab-stop.

Heavy STL headers

Don't add heavy STL includes in header files. Each of these #include s brings >20k lines of source code which needs to be preprocessed and compiled even if majority of it is later tossed out. Prefer to include these only in source files. The following headers are the heaviest, numbers taken from g++-4.8 -std=c++11 -E | wc -l:

• <algorithm> — 46k lines after preprocessing. Most of it are new C++11 features, with C++03 it had only ~10k.
• <istream> and friends — 22-24k lines after preprocessing. Use <iosfwd> instead and include stream headers only in source files. If you want to just print something to output, use Utility::Debug class and friends.
• <iterator> — includes stream headers, thus the same as above.
• <memory> — 25k lines after preprocessing.
• <random> — 36k lines after preprocessing.

In some cases, Corrade has forward declaration headers that help reduce the bloat in STL headers:

• Corrade/Utility/StlForwardString.h forward-declares std::string where possible
• Corrade/Utility/StlForwardTuple.h forward-declares std::tuple where possible
• Corrade/Utility/StlForwardVector.h forward-declares std::vector where possible

In C++17 and up, #include <cmath> is about 11k lines on libstdc++ due to new math additions such as std::riemann_zeta(). For this reason, directly including the <cmath> header is discouraged and you should be using Corrade/Utility/StlMath.h instead.

using namespace keyword

using namespace std is not allowed. It brings many symbols into default namespace and can lead to unintended behavior. Consider the abs() function. If using it without std:: prefix, you can by mistake use the non-overloaded double abs(double) from plain C <math.h> header, which can cause serious performance issues when using it for integers only. By explicitly calling std::abs() you ensure that proper overload is always selected.

using namespace keyword should be used only for root namespace, i.e. using namespace Corrade and not using namespace Corrade::Utility. If you are using some class from subnamespace in many places, use only that particular name, e.g. using Corrade::Utility::ConfigurationGroup and try to restrict it to as small block of code as possible (e.g. place the using only in function body). In general, where possible, choosing short, descriptive and not too deep name should be preferred to using the using keyword.

Similar guidelines apply to C++11 user-defined literals — restrict the using keyword to as small block of code as possible to avoid confusion:

{
    using namespace std::chrono::literals;
    time = 18h + 5m + 30s; // 18:05:30
}

It's probably common practice, but repeating won't hurt: headers shouldn't have using declarations at all (unless there is good excuse for bringing some useful feature from different namespace into another namespace — but not in the default namespace!).

C-style casts

Don't use C-style casts, use C++-style static_cast and reinterpret_cast instead. Corrade enables compiler warning about their usage in CORRADE_CXX_FLAGS CMake variable. You can also use "constructor cast" instead of static_cast when doing non-harmful conversions, such as integer to float or strongly-typed enum to its underlying type.

int a = 22;
int b = 7;
float pi = ((float) a)/b;           // bad!
float pi = static_cast<float>(a)/b; // good
float pi = float(a)/b;              // even better here

Unscoped and untyped enums

Prefer to use C++11 enum class. Use Containers::EnumSet instead of integral bit masks. Always explicitly specify underlying type, it might save some memory and also allows for forward declaration of the enum, which is good if the enum is part of otherwise large header.

static keyword

Prefer to use anonymous namespaces instead of static keyword. Anonymous namespace ensures that the symbols won't be exported and unlike static keyword it can be used also for type declarations.

Code

It's possible to annotate inline code with language as well. There's no difference in the output for the stock Doxygen HTML output, but the m.css theme can make use of it. The @cb command denotes beginning of inline code snippet and takes the language as an argument. Inline code end is denoted with @ce. To make things easier, there are @cpp and @cmake aliases that expand to @cb{.cpp} and @cb{.cmake}, respectively.

/** Returns @cpp Magnum::Vector2 @ce, which is @cb{.glsl} vec2 @ce in GLSL. */

Documentation-related TODOs

TODOs about documentation (or about Doxygen workarounds) should be written with @todoc instead of @todo. They will appear on separate page.

Debugging operators

Operators for printing types on Corrade's debug output should be marked with @debugoperator, e.g.:

/** @debugoperator{Hash} */
Corrade::Utility::Debug& operator<<(Corrade::Utility::Debug& debug, const Hash& value) {
    // ...
}

They will appear as related functions within documentation of class specified as the parameter and also crossreferenced from the Debug output operators for custom types page.

For non-class enums there is @debugoperatorenum command and for in-class enums the @debugoperatorclassenum command:

enum class Flag: std::uint32_t;

/** @debugoperatorenum{Flag} */
Corrade::Utility::Debug& operator<<(Corrade::Utility::Debug& debug, Flag value);

class Foo {
    enum class Flag: std::uint32_t;
};

/** @debugoperatorclassenum{Foo,Foo::Flag} */
Corrade::Utility::Debug& operator<<(Corrade::Utility::Debug& debug, Foo::Flag value);

Debug operator for non-class enum will appear in documentation of surrounding namespace, debug operator for class enum will appear as related function in documentation of given class.

Configuration value parsers and writers

Helper classes for parsing and writing Utility::Configuration values should be marked with @configurationvalue, and referenced from the class using @configurationvalueref e.g.:

/** @configurationvalueref{Hash} */
class Hash;

/** @configurationvalue{Hash} */
namespace Corrade { namespace Utility {
    struct ConfigurationValue<Hash> {
        // ...
    };
}

They will appear linked with documentation of class specified as the parameter and also crossreferenced from the Configuration value parsers and writers for custom types page.

Tweakable literal parsers

Utility::Tweakable literal parsers should be marked with @tweakableliteral, similarly to how it's done for configuration value parsers. They will appear linked with documentation of the class specified as a parameter and also crossreferenced from the Tweakable literal parsers page.

Partially supported features

Features that are not supported on all platform should be marked with @partialsupport, listing unsupported platforms and optionally reason why. They will be all crosslinked through the List of partially supported features page.

Third party dependency licensing info

Libraries, plugins and executables that make use of third party code should be visibly marked with @thirdparty, in a color-coded block according to the description in Third-party components and highlighting the license name as well. It should link to the original license text, ideally also to a matching overview on https://choosealicense.com and have a short sentence explaining the main requirements (e.g., whether it's attribution, source code release, dynamic linking, explicit licensing for commercial use etc.) Example:

/**
@m_class{m-block m-success}

@thirdparty This plugin makes use of the [HarfBuzz](http://harfbuzz.org/)
    library, licensed under @m_class{m-label m-success} **MIT**
    ([license text](https://raw.githubusercontent.com/behdad/harfbuzz/master/COPYING),
    [choosealicense.com](https://choosealicense.com/licenses/mit/)). It
    requires attribution for public use.
*/

Backwards compatibility and experimental features

Common practice is to keep backwards compatibility when refactoring APIs — if given feature is present for a considerable amount of time or is already part of some release, any change that breaks source compatibility should be complemented with backwards-compatible function or type alias that is marked as deprecated using @deprecated and one of CORRADE_DEPRECATED() macros. If given feature is still in experimental stage, maintaining backwards compatibility might hurt innovation — in that case the feature should be marked with @experimental.