Programming Style Guide

C++ style guide

MPQC is based on the Google C++ Style Guide (due to the lack of resources to develop our own from the ground up) with the following amendments (we are assuming educated developers!):

• the use of forward declarations and separation of template function/class declarations from their definitions is strongly recommended (see Code Organization for more details)
• use of exceptions is encouraged
• multiple inheritance is OK
• use of boost outside of approved cases is discouraged. The approved cases included boost libs that are already used and that are forbidden by gcxx: ptree, serialization, math, optional, locale
• use of unsigned integer types is OK
• use of non-const references as function arguments is OK
• compromise naming convention (rationale: MPQC3 uses CamelCase naming for most (all?) top-level classes, whereas internally many classes/functions use a_b_c style):
  • use CamelCase (e.g. BasisSet) for top-level functionality
  • variable and function names (including standalone, class members, lambdas, etc.) follow a_b_c pattern.
  • ok to append “_” to variable and function names that are private or protected members. Public members should not end in “_”.

Enforcing code style

Enforcement of the style guide recommendations as well as other accepted coding practices should be as automated as possible. It is possible to configure a modern IDE to do this job or it can be done by the pre-commit hooks packaged with MPQC. We recommend to use the pre-commit hooks, since they can be used to do much more than just enforce style guide.

git hook: clang-format

As described in pre-commit git hooks MPQC contributors should use pre-commit hooks to automate code maintenance and enforce coding conventions. One of the pre-commit hooks reformats the code to follow the MPQC style using the clang-format program. To be able to use this hook you should install the clang-format program (available standalone as well as part of the LLVM packages on both Linux and MacOS platforms).

This hook runs clang-format using style file .clang-format located at the top of MPQC repository. Any time a C++ file is changed clang-format will be run on it; if any changes are necessary it will mutate the file in-place and the commit will fail. You will need to commit again (you may also need to fix any other errors identified by pre-commit; see pre-commit git hook: clang-format for more info).

Sometimes you way want to protect parts of code from being re-formatted by clang-format, due to readability or correctness concerns. This can be done by adding // clang-format off immediately before the lines you want to protect and // clang-format on after the lines that you want to protect, e.g.:

int formatted_code;
// clang-format off
    void    unformatted_code  ;
// clang-format on
void formatted_code_again;

Refer to the clang-format documentation for more info.