anki-3d-engine/docs/code_style.md

This document describes the code style of AnKi 3D Engine.

Comments

All comments are C++ like:

// Some comment

And for doxygen comments:

/// @brief blah blah
/// @param blah blah

Naming Conventions

Variables, functions and methods are lower camelCase.

functionDoSomething(someVariableA, someVariableB);

All types are PascalCase and that includes classes, structs, typedefs and enums.

enum MyEnum {...};
class MyClass {...};
using MyType = int;

All constant expressions are SCREAMING_SNAKE_CASE and that includes enumerants.

constexpr int MY_CONSTANT = ...;

enum MyEnum
{
    ENUMERANT_A
};

All macros and defines should be SCREAMING_SNAKE_CASE and they should have an ANKI_ prefix.

ANKI_ASSERT(...);

#define ANKI_MAX_SOMETHING ...

All template arguments should start with T.

template<typename TSomething, typename TOther, U32 T_SOME_CONST>

The source files are always PascalCase.

ThreadHive.h
MyShaderProgram.ankiprog

All function and method names should form a sentence with at least one verb.

doSomething(...);
getSomething();
calculateSomething(...);

No hungarian notations with 2 exceptions.

• All member variables have the m_ prefix.
• All global variables have the g_ prefix.

C++ rules

Always use strongly typed enums. If you need to relax the rules use the ANKI_ENUM_ALLOW_NUMERIC_OPERATIONS macro.

enum class MyEnum : uint {...};
ANKI_ENUM_ALLOW_NUMERIC_OPERATIONS(MyEnum, inline);

Never use typedef to define types. Use using instead.

using U32 = uint32_t;
using Func = void(*)(int, int);

Never use C-style casting. Use static_cast, reinterpret_cast or const_cast for most cases and constructor-like cast for fudmental types.

Derived* d = static_cast<Derived*>(base);

uint i = uint(1.1f); // uint is fudmental type

Always use constexpr when applicable. Never use defines for constants.

constexpr uint SOME_CONST = ...;

Never use struct and always use class instead. Since it's difficult to come up with rules on when to use struct over class always use class and be done with it.

class MyTrivialType
{
public:
    int m_x;
    int m_y;
};

Avoid using auto. It's only allowed in some templates and in iterators. auto makes reading code difficult.

Includes should always have the full file path. This avoids issues with files of similar name. Non-AnKi includes follow AnKi includes.

#include <anki/util/Thread.h>
#include <anki/util/WeakArray.h>
#include <anki/util/Allocator.h>
#include <cstdio>

Never use public nested classes. Only private nested classes are allowed. Nested classes cannot be forward declared.

class MyClass
{
public:
    // NO!!!!!!!!!!!
    class Nested {...};

private:
    // It's fine
    class Nested {...};

    // Also fine
    class
    {
        ...
    } m_myUnamedThing;
};

Try to use explicit in constructors for extra safety. Don't use explicit on copy constructors.

AnKi uses const correctness throughout and that's mandatory. Always use const. The only place where you don't have to is for function and method parameters.

uint doSomething(uint noNeedForConst)
{
    const uint bla = noNeedForConst + 10;
    return blah;
}

Access types in a class have a specified order. First public then protected and last private. There are some exceptions where this rule has to break.

class MyClass
{
public:
    ...
protected:
    ...
private:
    ...
};

Always use AnKi's fudmental types (U32, I32, F32, Bool etc etc). For integers and if you don't care about the size of the integer you can use the type U for unsinged or I for signed. Both of them are at least 32bit.

for(U32 i = 0; i < 10; ++i) {...}

If you have to overload the operator Bool always use explicit operator Bool operator overloading.

explicit operator Bool() const {...}

The use of references and pointers is govern by some rules. Always use references except when you transfer or share ownership where you should use pointers. Pointers are also allowed for optional data that can be nullptr.

// ptr is a pointer so you CAN NOT destroy it after a call to doSomething is done
// ref is a reference so you CAN destroy it after a call to doSomething is done
void Foo::doSomething(TypeA* ptr, TypeB& ref)
{
    // Store the ptr somewhere
    m_someMember = ptr;

    // Won't store the ref
    ref += ...;
}

Always use nullptr.

void* ptr = nullptr;

Never use C style arrays. Use the Array<> template instead.

Array<MyType, 10> myArray;

Don't use STL. AnKi has a replacement for most STL templates. There are some exceptions though.

• Can use type_traights.
• Some from utility eg std::move.
• Some from algorithm eg std::sort.

Always try to comment parts of the source code. Self documenting code is never enough.

Always use override or final on virtual methods and try to use final on classes when applicable.

class Foo final
{
public:
    void myVirtual(...) override {...}
};

Code formatting

clang-format deals with code formatting. To format the whole source tree type the following in a terminal:

$ cd /path/to/anki
$ ./tools/format_source.sh

If you need to format on Windows do the same from a WSL terminal.

Some cases that are not handled by clang-format follow.

Always use curly braces on single line expressions.

// NO!!!!!!!!!!!
if(something) doSomething();

// YES!!!!!!!!!!!!!!
if(something)
{
    doSomething();
}

Always place the condition of a conditional ternary operator inside parenthesis.

// NO!!!!!!!!!!!
a = b ? 1 : 0;

// YES!!!!!!!!!!!!!!
a = (b) ? 1 : 0;