Coding Conventions and Style

Function definition conventions

We have the convention whereby the output variables from a function are ordered first, with inputs and constants coming after these. E.g., we prefer

template <typename T> void foo(T &out, const T &in);

as opposed to

template <typename T> void foo(const T &in, T &out);

Coding Style and Clang Format

For coding style we use clang-format to enforce our preferred coding formatting style. At present, we utilize clang-format v11.

The file .clang-format defines our style. Please check this file together with the documentation of the options if you want to know more.

Applying clang-format

Applying clang-format globally will introduce a lot of changes that may result in merge conflicts and render diffs quite useless.

We therefore only apply clang-format to lines of code that have been changed anyway or to parts of code where most lines have changed, e.g. you have reimplemented a function and only the header and a few lines of the original code have not been touched.

For the future we might look into using git-clang-format for this

Applying it to lines changes in a pull request

For reformatting only a diff you can use clang-format-diff.py. Note that by default it does not touch CUDA-files, i.e. .cu and .cuh files.

Hence it is convenient to create a hacked version that changes the part of the code

  parser.add_argument('-iregex', metavar='PATTERN', default=
                      r'.*\.(cpp|cc|c\+\+|cxx|c|cl|h|hpp|m|mm|inc|js|ts|proto'
                      r'|protodevel|java)',
                      help='custom pattern selecting file paths to reformat '
                      '(case insensitive, overridden by -regex)')

to include cu and cuh in the list of files extensions:

  parser.add_argument('-iregex', metavar='PATTERN', default=
                      r'.*\.(cpp|cc|c\+\+|cxx|c|cl|h|hpp|m|mm|inc|js|ts|proto'
                      r'|protodevel|java|cu|cuh)',
                      help='custom pattern selecting file paths to reformat '
                      '(case insensitive, overridden by -regex)')

Then if you have a pull ready for review in your branch named feature/format-me for merge into develop you can get a diff of your changes by:

git diff  develop...feature/format-me ':(exclude)tests/googletest/*' ':(exclude)lib/generate/*' ':(exclude)lib/dslash_core/*' 

Note: The diff is done locally, so make sure your local version of develop is up-to date with the one on GitHub.

To apply clang-format to these changes use

git diff -U0  --no-color  develop...feature/format-me ':(exclude)tests/googletest/*' ':(exclude)lib/generate/*' ':(exclude)lib/dslash_core/*' | clang-format-diff.py -i -p1

Applying clang-format to selected regions of your code

For this it is recommended to rely on clang-format support in your editor. Check https://clang.llvm.org/docs/ClangFormat.html for some editors or search for clang-format integration for you preferred editor on the web.

Feel free to add your configuration and the tools you use here to help others.