Home

Welcome to the wiki of GMGPolar.

C++ Coding Guidelines

C++ Standard:

• C++ 14

Naming rules:

• Classes begin with small letters , e.g. class myclass
• functions, methods, variables use small letters + underscore, e.g. my_awesome_function

Exceptions:

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

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)
  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 A
{
namespace B
{
    /*some code*/
} // namespace B
} // namespace A

Definitions and Declarations

• Braces in new lines:

class Model
{

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 X_Y:
    return zmax - zmin;
case X_Z:
    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.