Coding style

Runko tries to conform to common C++ and Python3 styles. The motivation is to provide

  1. a uniform code base that is familiar to everybody,

  2. enforce a coding style that is less error prone, and

  3. encourage more succint notation since less code means less bugs.

These styles can be enforced and checked with various tools, that are run manually from time to time.

General guidlines

  • use “snake_case” for variable and function names, i.e., ex, gam, get_container()

  • objects and classes are named with a Capital letter and using the CamelCase form, i.e., Tile, ParticleContainer

  • use short but descriptive naming that resembles the underlying mathematical formulas

  • stick to <100 character long lines.

  • surround + and - operators with a space for easier visibility, i.e., 2*x + y.

  • do not use tabs but normal spaces for indentation.

  • Python indentation level is 4 spaces and C++ is 2; this enforces more compact code.

Black

black is an uncompromised Python code formatter that is also PEP 8 compliant. In general, we try to conform to the output of black as much as possible, but we do deviate sometimes, in the name of more succint expressions.

Format a python script by running

black some.py

Note

Black overwrites the file. It is typically easiest to apply it by first developing your code as normal, then commiting to the git. After that, finish by running black on your python files. You can then check the changes with git diff and see that they make sense.

clang-tools

Clang-tools are a set of code formatting, analysis, and testing tools based on the LLVM compiler set that aim to make C++ code more readable and less bugprone.

In order to use the tools, first we need to create a compile-commands.json file that provides a recipe for the LLVM compiler how to compile each file. For details, see [CD1], [CD2].

To generate the compile-commands.json with CMake, run it in the runko/build/ directory with

cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=1 ..

And prune it manually by removing unwanted files (like those of the included libraries, corgi/*, corgi/mpi4cpp/ etc.).

Clang-Format

The C++ files are regularly checked and formatted with Clang-Format. Runko ships with a clang-format configuration file at the top level of the repository (filename .clang-format).

Currently formatting is not applied automatically, but manually using clang-format for newly developed files is highly encouraged. To check if a file needs formatting,

clang-format -style=file --dry-run some.c++

The output will show what needs to be changed, if any. To automatically apply the changes,

clang-format -style=file -i some.c++

Clang-Tidy

Clang-Tidy is a similar but more heavy-weight tool that performs a deeper static code analyses and checks for bugprone code etc.

We typically test the code with checks from:

  • modernize-*

  • performance-*

  • bugprone-*

  • readability-*

  • mpi-*

  • cppcoreguidlines-*

in roughly the given order.

A helper python script exists in tools/ to perform the analysis for all files. Run the script (still in the runko/build/ directory) with

python3 ../tools/run-clang-tidy.py -header-filter='.*' -checks='-*,modernize-*'
python3 ../tools/run-clang-tidy.py -header-filter='.*' -checks='-*,performance-*'
python3 ../tools/run-clang-tidy.py -header-filter='.*' -checks='-*,readability-*'
python3 ../tools/run-clang-tidy.py -header-filter='.*' -checks='-*,bugprone-*'
python3 ../tools/run-clang-tidy.py -header-filter='.*' -checks='-*,cppcoreguidlines-*'

Use common sense what fixes to actually apply.

Include-what-you-use

To run include what you use, install (brew install include-what-you-use on macOS), then run:

cmake -S . -B build-iwyu -DCMAKE_CXX_INCLUDE_WHAT_YOU_USE=$(which include-what-you-use)

cmake --build build

Warning

TODO: not implemented yet.

References