In order to keep the code maintainable we have decided upon a set of coding rules. Some of them may seem like splitting hairs to you, but they do make it much easier for everybody to work on code that hasn’t been written by oneself. We recognize that these rules are not honored in all places. In most cases, these naming rule violations are considered bugs, but there are some exceptions.

Code Formatting:

• Indentation: Indentation happens using spaces only, the indentation depth is two per level. As different people have different default settings for this, it is good practice to place editor hints at the beginning of new files. Just start any new file with

  // -*- tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
  // vi: set et ts=4 sw=2 sts=2:
  

  The indentation and many other formatting rules are formalized in a configuration file dune-uncrustify.cfg for the uncrustify tool. You can format new files using this tool by calling

  uncrustify -l CPP -c dune-uncrustify.cfg <FILENAME>
  

• Trailing Whitespace: Source files may not contain trailing whitespace to reduce the amount of noise in diffs and during merges.

Some code formatting rules are enforced automatically (see below).

Naming

• Variables: Names for variables should only consist of letters and digits. The first letter should be a lower case one. If your variable names consists of several words, then the first letter of each new word should be capital. As we decided on the only exception are the begin and end methods.
• Acronyms: Capitalization never changes within acronyms. Hence return ABC() and abcSize() are valid method names, but return Abc() is not.
• Private Data Variables: Names of private data variables end with an underscore.
• Typenames: For typenames, the same rules as for variables apply. The only difference is that the first letter should be a capital one. Types exported by other types never end with a Type-suffix.
• Macros: The use of preprocessor macros is strongly discouraged. If you have to use them for whatever reason, please use capital letters only.
• The Single-Inclusion Macro: Every header file traditionally begins with the definition of a preprocessor constant that is used to make sure that each header file is only included once (the single-inclusion macro). To avoid name clashes, this macro should encode the file name together with the entire path of that file within the Dune module. Slashes are replaced by underscores, and capital letters are used exclusively. For example, if your header file is 'dune/mymodule/common/myheaderfile.hh', this constant should be DUNE_MYMODULE_COMMON_MYHEADERFILE_HH.
• Files: Filenames should consist of lower case letters exclusively. Header files get the suffix .hh, implementation files the suffix .cc

There are a few classes which are exempt from these rules. Those are classes that directly implement a concept from the standard library (e.g., container classes). Unlike demanded above, such classes are to follow the STL naming style exclusively, to allow to use them directly in STL contexts. To mark such classes, they are to live in a separate namespace Dune::Std.

Documentation

Dune, as any software project of similar complexity, will stand and fall with the quality of its documentation. Therefore it is of paramount importance that you document well everything you do! We use the doxygen system to extract easily-readable documentation form the source code. Please use its syntax everywhere. In particular, please comment all

• Method Parameters
• Template Parameters
• Return Values
• Exceptions thrown by a method

Since we all know that writing documentation is not well-liked and is frequently deferred to some vague ’next week’, we herewith proclaim the Doc-Me Dogma . It goes like this: Whatever you do, and in whatever hurry you happen to be, please document everything at least with a /** \todo Please doc me! */. That way at least the absence of documentation is documented, and it is easier to get rid of it systematically.

Exceptions

The use of exceptions for error handling is encouraged. There is a variety of Dune-specific exceptions you can throw. They all derive (possibly indirectly) from the class Dune::Exception in dune-common.

Output

The header stdstreams.hh defines several output streams for messages of varying urgence. Depending on the desired verbosity of the code these can be switched on and off by special options of the ‘configure’ command.

Debugging Code

Global debugging code is switched off by setting the symbol NDEBUG. In particular, all asserts are automatically removed. Use those asserts freely!

Automatic Enforcement

There are currently two options for enforcing some of the formatting rules automatically.

The git Whitespace Hook

Source code changes that introduce trailing whitespace at the end of a source code line are rejected by the version-control system using a git hook.

Due to the distributed nature of Git, the server cannot check your commits as you create them in your locally cloned repository. Instead, you should install our local whitespace hook that checks every commit when trying to push it to the server, and rejects those that contain whitespace problems. Then you can easily fix those problems, stage the additional changes and re-commit.

The hook is installed by calling

dunecontrol vcsetup

You can call this explicitly, but it is also part of

dunecontrol all

Note that if you push a sequence of commits, the server checks all commits for trailing whitespace. This means that you cannot fix a rejected commit by adding an extra commit that resolves the whitespace problem in the original commit. Instead, you have to rewrite your local history with interactive rebasing.

Automatic code formatting

You can verify compliance with the code formatting rules locally by running the uncrustify tool with the official Dune configuration file dune-uncrustify.cfg. To do this, run

uncrustify -l CPP -c dune-uncrustify.cfg --no-backup `find -name "*.cc" -o -name "*.hh"`

in your source directory. If this does not modify the code, then your formatting is correct. (Unfortunately, the behavior of uncrustify changes slightly from version to version).

You can get the GitLab CI to check formatting compliance. To do this, add the following snippet to the file .gitlab-ci.yml of your Dune module:

# Verify code-formatting rules
code-formatting-check:
  stage: .pre
  # Avoid the global 'before_script'
  before_script: ""
  image: registry.dune-project.org/docker/ci/debian:13
  script:
    # Format all *.cc and *.hh files using the uncrustify tool
    - uncrustify -l CPP -c dune-uncrustify.cfg --no-backup `find -name "*.cc" -o -name "*.hh"`

    # Did anything change?  That would indicate a violation of the formatting rules
    # But before, work around an issue where git doesn't recognize the source tree as a git directory.
    # See https://forum.gitlab.com/t/ci-cd-job-git-diff/76666
    - git config --global --add safe.directory "$(pwd)"
    - git diff --exit-code

This set ups a CI job that checks for proper code formatting. With this, any merge request will fail CI testing if it introduces code changes that violate the formatting rules.

When starting to use uncrustify to enforce proper code formatting of a Dune module, typically one large reformatting commit has to be made that applies large amounts of white-space changes to pretty much every source file. This commit appears in the git history and clutters the output of git blame. If you are bothered by this, you can tell git blame to ignore the commit by writing the commit id to a file named .git-blame-ignore-revs, and calling git blame as

git blame --ignore-revs-file=.git-blame-ignore-revs <file>