cpp coding guidelines

C++ Coding Guidelines

C++ Standard:

• C++ 14, higher standards are currently not allowed

Namespaces:

• Use the epi namespace.

Naming rules:

• Classes begin with large Letters , e.g. class MyClass
• functions, methods, variables use small letters + underscore, e.g. my_awesome_function
• member variables should be generally private (we allow exceptions from this rule) and should be named with a leading "m_", e.g. m_my_member.

Return Values:

• If only one object is output, use return, for multiple objects, pass by reference (we still have to check std::expected)
• The semantics of return value arguments have to make clear, how the ownership is handled
  • If the function creates an object (allocates), pass it as std::unique_ptr<T>&
  • If the function simply changes an object, pass is as T&

Exceptions:

• In order to avoid MPI deadlocks, do not use exceptions. Use logging or return codes.

Logging:

• Do not use printfs
• Use the logging functions from logging.h
• For debug logs, use epi::log_debug(msg)

Includes:

• Please use include guards with capitalized name of the header file (test.h -> #ifndefine TEST_H)
• Sort includes according to
  1. own header
  2. headers from the same library
  3. specific third party library (e.g., hdf5, and eigen)
  4. general third party/standard library

Code Documentation:

• Use doxygen docstrings

Mandatory C++ Style Guidelines

The style guidelines are adopted from TiGL.

General style

Tabs and Indentation

• Use 4 spaces indentation. Don't use tabs!
• Exceptions:
  • public/protected/private keywords in class definitions
  • namespace epi

namespace epi
{
namespace foo
{
    namespace bar 
    {
        /*some code*/
    }
}
} // namespace epi

Definitions and Declarations

• Braces in new lines:

class Secir
{

private:
    double m_member;
};

• If you use several lines for a functions definition/declaration, align the function arguments horizontally

ReturnCode compute_something(Arg1 arg1,
                             Arg2 arg2,
                             Arg3 arg3)

Loops, If and Switch Statements

• space before and after condition
• Braces in the same line

if (psi.size()<=2) {
    psi.clear();
}
else {
    double psimax = psi[psi.size()-1];
}

for (size_t i = 0; i < psi.size(); i++) {
    some code
}

switch (GetSymmetryAxis()) {
case TIGL_X_Y_PLANE:
    return zmax - zmin;
case TIGL_X_Z_PLANE:
    return ymax - ymin;
}

Automatic code formatting with clang-format

The Clang-Format Tool can also be used to reformat the code to our style. Here are the settings that should comply to our style.

BasedOnStyle: LLVM
IndentWidth: 4
SortIncludes:    false
ColumnLimit:     120
AlignTrailingComments: false
AccessModifierOffset: -4
AlignConsecutiveAssignments: true
ReflowComments:  false
BraceWrapping:   
  AfterClass:    true
  AfterFunction: true
  BeforeElse: true
  BeforeCatch: true
  AfterNamespace:  true
  AfterEnum: true
BreakBeforeBraces: "Custom"
PointerAlignment: Left
AllowShortFunctionsOnASingleLine: false
NamespaceIndentation: Inner
BreakConstructorInitializersBeforeComma: true
AlwaysBreakTemplateDeclarations: Yes
AllowShortLambdasOnASingleLine: Empty

These settings are set in the file .clang-format in the root directory of the repository. The Beautifier plugin shipped with QtCreator supports clang-format (help could also be provided by https://www.vikingsoftware.com/using-clang-format-with-qtcreator/), so you will be able to automatically format your code. For Visual Studio Code or VSCodium, install the Clang-format extension and add the lines:

"editor.formatOnSave": true,
"clang-format.executable": "...path...to...clang-format-executable",

to your settings.json and store the above code formatting rules in a file named ".clang-format" in the working directory of VSCode or VSCodium. For VSCodium, the clang-format extension is not in the marketplace and has to be installed manually via

codium --install-extension EXTENSION.vsix

Note: The clang-format provided by default in Debian/Ubuntu is quiet old and with our style file the issue

AlwaysBreakTemplateDeclarations: Yes
                                 ^~~
Error reading PATH/.clang-format: Invalid argument

might appear. In that case, update clang-format or install a newer version (e.g. clang-format-10) manually and point to its executable.