C++ Coding Guidelines

Best Practices

1. NEVER include using namespace statements in header files.

2. NEVER include a using statement for the standard namespace (std). Instead, always qualify all types from it.

3. USE a constexpr expression instead of a MACRO whenever possible.

4. USE pragma once instead of header guards.

5. USE enum class instead of enum whenever possible.

6. ALWAYS declare variables as close to first usage as possible - this isn't C!

7. ALWAYS pass non-trivial parameters by reference.

8. PREFER a composite return value (e.g. pair, POD struct) to multiple out parameters.

9. PREFER auto whenever possible, but use as many type modifiers (const, volatile, &, *) as possible.

10. AVOID volatile unless there is a very strong justification (there usually isn't).

11. ALWAYS use using statements instead of typedef for aliases.

12. USE function qualifiers (override, final, const) liberally.

13. PREFER an enumeration to multiple booleans.

14. USE anonymous namespaces liberally in cpp files and export the minimum number of names from each compilation object.

15. NEVER use static free functions.

File / Directory Layout

If a cpp/h file contains a single class, the file should be named after the class and be UpperCamelCase. If a cpp/h file contains utility functions, the file should be given a descriptive name and be UpperCamelCase.

We expect parallel source and test directory hierarchies. For example,

root
- parser  # package name, directory containing source code
  Parser.h/cpp  # contains class Parser
  - ast
    - Ast.h/cpp  # contains various exports

- tests  # directory containing tests for source code
  - ParserTests.cpp  # unit tests for parser/Parser.h/cpp
  - ast
    - AstTests.cpp  # unit tests for parser/ast/Ast.h/cpp

Naming

1. Static and free functions should be UpperCamelCase

2. Member function names should be lowerCamelCase

3. Constants (global or local) should be Upper_Camel_Case.

4. #defines should be TITLE_CASE

5. Local variables and function parameters should be lowerCamelCase

6. Struct members should be UpperCamelCase

Includes

1. Always use "/" in includes and NEVER "\", (C standard WG14/N1256 point 6.4.7, C++ standard ISO/IEC 14882:2003 point 2.8, C++ standard ISO/IEC 14882:2011 (from working draft N3225) point 2.9)

2. Try to include the minimal number of files required for a successful build. Corollary: don't include anything you don't need.

3. Order includes from most specific to most general.

Style

for (auto&& pEntity : entities) {
    singleEntityVector[0] = pEntity;
    auto result = dispatcher.dispatch(m_config.ValidationPolicy, singleEntityVector);
    m_config.pObserver->notify(*pEntity, observerContext);
}

CATAPULT_LOG(debug) << "comparing chain scores: " << localScore << " (local) vs "
        << remoteScore << " (remote)";
return pState
        && pState->ImportanceInfo.Importance > Importance(0)
        && pState->Balances.get(Xem_Id) >= minHarvestingBalance;

// mind the double indent for method arguments
thread::future<std::unique_ptr<model::Block>> BlockAt(
        Height height,
        const io::BlockStorageView& storage) {
    if (Height(0) == height || storage.chainHeight() < height) {
        auto exception = CreateHeightException("unable to get block at height", height);
        return thread::make_exceptional_future<std::unique_ptr<model::Block>>(exception);
    }

    return thread::make_ready_future(storage.loadBlock(height));
}

Foo() : m_value(0)
{}

// two indents
Foo(very arguments, much wow)
        : m_value(0)
        , m_xman(professor)
{}

Foo() : m_value(0) {
    // body
}

// two indents
Foo(very arguments, much wow)
        : m_value(0)
        , m_xman(professor) {
    // body
}