This page describes general and coding conventions used in preCICE.

## General guidelines

• Main rule: orient yourself on the already written code.
• CamelCase notation is used, no underlines please.
• Make sure your code compiles before you commit.
• Pay attention to compiler generated warnings and try to fix them.
• In case you can’t fix a unused variable warning, e.g. with range based for loops, you can use std::ignore = vertex; // Silence unused variable warning.
• Use std::vector::empty() to check for emptiness, not vector.size() == 0. empty() is guaranteed to be O(1) for all STL container classes. Furthermore, it says what you are actually doing.
• Use #pragma once as an include guard.
• Use std::make_shared for creating smart pointers. Why: Difference in make_shared and normal shared_ptr in C++

## Indention and formatting

As a rule of thumb again: Orient yourself on the already written code!

There is a settings file for clang-format. See the page on \ref tooling for more information on clang-format.

Regarding indention, we follow the BSD-style.

We do not indent namespaces since three or so levels of nested namespaces fill the offset without adding any viable information.

Using Emacs you get the indention style using this snippet.

(setq c-basic-offset 2)
'("bsd" (c-offsets-alist . (
(innamespace . 0)
(namespace-open . 0)
(namespace-close . 0)
(cpp-macro . 0) ; indent macros like the surrounding code
))))
(setq c-default-style "my-cc-style")


## Documentation

We use Doxygen for source code documentation. A generic documentation template for a class, function or variable:

/// A brief doc string, just one line
/** Some more elaborate description following, it is optional
* @param[in] i Parameter going into the function
* @param[out] o Parameter coming from the function
* @param[in,out] x One more parameter, used for input and output
*/
void foo(int i, double o, bool x);


For a one-line documentation you should use

/// Eat an apple
void eat(Apple a);


For more information, see the page on \ref tooling.

## Dimension-ordering

Under dimension-ordering, the ordering of some indices associated to a multi-dimensional structure (e.g., cell) in a specific way is understood. The index 0 is associated to the object which has coordinates nearest to 0 for all dimensions. Index 1 is given to the object with coordinates nearest to zero, besides for dimension 1. The following example illustrates the ordering. The example shows the numbering of sub-cells in a 2D cube:

      ---------
| 2 | 3 |
dim 2 |-------|
^   | 0 | 1 |
|   ---------
--> dim 1