Check your code

Below, we provide tools and scripts that you can use to check the formatting of your code. Before you get started, please take a look at our detailed guidelines for C++ coding in NEST

Development environment

We have provided an environment.yml file that contains all packages to do development in NEST, including the tools to check coding style.

See our instructions on installing NEST from source.

Tooling

The clang-format tool is built on the clang compiler frontend. It prettyprints input files in a configurable manner, and also has Vim and Emacs integration. We supply a clang-format-file (<build_support/format_all_c_c++_files.sh> to enforce some parts of the coding style. During the code review process we check that there is no difference between the committed files and the formatted version of the committed files.

Developers can benefit from the tool by formatting their changes before issuing a pull request. For fixing more files at once we provide a script that applies the formatting.

From the source directory call:

./build_support/format_all_c_c++_files.sh [start folder, defaults to '$PWD']

The code has to compile without warnings (in the default settings of the build infrastructure). We restrict ourselves to the C++11 standard for a larger support of compilers on various cluster systems and supercomputers.

We use clang-format version 13 in our CI. If your clang-format executable is not version 13, you need to specify an executable with version 13 explicitly with the –clang-format option to ensure consistency with the NEST CI.

Furthermore, we use Vera++, which ‘is a programmable tool for verification, analysis and transformation of C++ source code’. It enables further checks for the code complying to the coding guidelines. We provide the vera-profile-nest (<build_support/vera++.profile>) file in the repository (which needs to be copied/symlinked into vera++home>/lib/vera++/profiles/). We then check that there are no messages generated by the execution of the following command:

vera++ -profile nest <committed file>

Finally, we let cppcheck statically analyse the committed files and check for severe errors. We require cppcheck version 1.69 or later.

cppcheck --enable=all <committed file>

Note

For Python, we enforce PEP8 formatting.

Local static analysis

We ship a script ./build_support/check_code_style.sh that lets you perform the checks on all changed files as we do during the Travis CI tasks.

$ ./build_support/check_code_style.sh --help
Usage: check_code_style.sh [options ...]

Usage: ./build_support/check_code_style.sh [options ...]

This script processes C/C++ and Python source code files to verify compliance with the NEST
coding  style  guidelines.  The  checks are performed the same way as in the NEST Travis CI
build and test environment. If no file is specified, a local 'git diff' is issued to obtain
the changed files in the commit range '<git-sha-start>..<git-sha-end>'. By default, this is
'master..head'.

The script expects to be run from the base directory of the NEST sources,
i.e. all executions should start like:
 ./build_support/check_code_style.sh ...

The setup of the tooling is explained here:
https://nest-simulator.readthedocs.io/en/latest/contribute/coding_guidelines_cpp.html

Options:

    --help                           This help.

    --[i]ncremental                  Prompt user before each file analysis.

    --file=/path/to/file             Perform the analysis on this file.

    --git-start=Git_SHA_value        Hash value (Git SHA) from which Git starts the diff.
                                     Default: --git-start=master

    --git-end=Git_SHA_value          Hash value (Git SHA) at which Git ends the diff.
                                     Default: --git-start=HEAD

    --vera++=exe                     The name of the VERA++ executable.
                                     Default: --vera++=vera++

    --cppcheck=exe                   The name of the CPPCHECK executable.
                                     Default: --cppcheck=cppcheck
                                     Note: CPPCHECK version 1.69 or later is required.
                                           This corresponds to the version installed in
                                           the NEST Travis CI build and test environment.

    --clang-format=exe               The name of the CLANG-FORMAT executable.
                                     Default: --clang-format=clang-format
                                     Note: CLANG-FORMAT version 13 is required.

    --pep8=exe                       The name of the PEP8 executable.
                                     Default: --pep8=pep8

    --perform-vera=on/off            Turn on/off VERA++ analysis.
                                     Default: --perform-vera=on

    --perform-cppcheck=on/off        Turn on/off CPPCHECK analysis.
                                     Default: --perform-cppcheck=off

    --perform-clang-format=on/off    Turn on/off CLANG-FORMAT analysis.
                                     Default: --perform-clang-format=on

    --perform-pep8=on/off            Turn on/off PEP8 analysis.
                                     Default: --perform-pep8=on

Assuming you are in source directory of NEST and you want to check all changed files between the commits 104d47c0 and d66e4465, execute the following line:

./build_support/check_code_style.sh --git-start=104d47c0 --git-end=d66e4465