Skip to content

cpp coding guidelines

Jump to bottom
Henrik Zunker edited this page Feb 17, 2023 · 12 revisions

C++ Coding Guidelines

C++ Standard:

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

Namespaces:

  • Use the mio 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 mio::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. In particular
    • Write an explicit @brief for method documentsions. Continue the detailed description in the next line.
    • Always start a line with a capital letter and end with a dot.
    • The plural of classes, objects etc. should be denoted with a % sign between class name and plural s, e.g., Household%s. This is in order to visualize it correctly and provide a link on the doxygen page.
    • Use [in], [out], or [in, out] after @param in order to clarify if parameters are used as input, output or in- and output parameters.
    • To reference to enums put a # sign before the name.
    • Plase also provide a description for member variables; use ///< DESCRIPTION or /**< DESCRIPTION */ for two lines. Keep it short.

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
    • namespaces
namespace mio
{
namespace foo
{
namespace bar 
{
    /*some code*/
} // namespace bar
} // namespace foo
} // namespace mio

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: None
BreakConstructorInitializersBeforeComma: true
AlwaysBreakTemplateDeclarations: Yes
AllowShortLambdasOnASingleLine: Empty

These settings are set in the file .clang-format in the root directory of the repository.

Using clang-format with either Qt, Visual Studio Code, or VSCodium

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, 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.

Note: The clang-format provided by default in Debian/Ubuntu is quite 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.

Clone this wiki locally