.. _check_code:

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 :ref:`detailed guidelines for C++ coding in NEST <code_style_cpp>`

Development environment
-----------------------

We have provided an `environment.yml <https://github.com/nest/nest-simulator/blob/master/environment.yml>`_ file that contains all packages to do development
in NEST, including the tools to check coding style.

See our :ref:`instructions on installing NEST from source <dev_install>`.


Tooling
-------

The `clang-format <http://clang.llvm.org/docs/ClangFormat.html>`_ 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:

.. code::

   ./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++ <https://bitbucket.org/verateam/vera/wiki/Home>`_, 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:

.. code:: sh

   vera++ -profile nest <committed file>


Finally, we let `cppcheck <http://cppcheck.sourceforge.net/>`_ statically analyse
the committed files and check for severe errors. We require cppcheck version
1.69 or later.

.. code:: sh

   cppcheck --enable=all <committed file>


.. note::

  For Python, we enforce `PEP8 <https://www.python.org/dev/peps/pep-0008/>`_ 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.

.. code:: sh

   $ ./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:

.. code:: sh

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