CONTRIBUTING.md 4.52 KB
Newer Older
1 2
# GIT Workflow

Praetorius, Simon's avatar
Praetorius, Simon committed
3 4 5 6
Follow the ideas of [a-successful-git-branching-model](http://nvie.com/posts/a-successful-git-branching-model),
especially
- Create a new branch for all new features, following the naming convention
  `feature/XYZ`
7 8
- Merge features in the `develop` branch only
- Correct Bugs in issue branches, following the naming convention `issue/XYZ`
Praetorius, Simon's avatar
Praetorius, Simon committed
9 10
- Merge issues in the `develop` branch, except when it is a hotfix, then merge
  to `master` and `develop`
11 12
- For all merges create a meaningful *Merge Request* in GitLab

Praetorius, Simon's avatar
Praetorius, Simon committed
13 14
# Code Style-Guide

Praetorius, Simon's avatar
Praetorius, Simon committed
15 16 17
This style-guide is intended for developers writing code for AMDiS, is not complete
and probably not applied to all parts of the AMDiS code. Feel free to edit existing
source files in order to fulfill the styles.
Praetorius, Simon's avatar
Praetorius, Simon committed
18

Praetorius, Simon's avatar
Praetorius, Simon committed
19 20
Parts of this convention are taken from well established style guides, like the
*Google C++ Style Guide*.
Praetorius, Simon's avatar
Praetorius, Simon committed
21

22 23
In general, the code should follow the [C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines).

Praetorius, Simon's avatar
Praetorius, Simon committed
24 25
## File naming conventions

Praetorius, Simon's avatar
Praetorius, Simon committed
26 27 28 29 30
Filenames should be mixed lower and upper case, starting with an uppercase letter.
They should not include underscores or dashed. Use an uppercase letter to indicate
a new subword. Sourcefiles should end in `.cpp` and header files should end in `.hpp`.
In case you move the code of a template class to a separate file, included textually
at the end of the corresponding header file, use the extensions `.inc.hpp`.
Praetorius, Simon's avatar
Praetorius, Simon committed
31 32 33 34 35 36 37 38

The name of a file should follow the name of the implemented class in this file.

Examples of valid filenames:
* `AdaptInstat.hpp`
* `AdaptInstat.cpp`
* `DOFVector.hpp`
* `DOFVector.cpp`
Praetorius, Simon's avatar
Praetorius, Simon committed
39 40
* `DOFVector.inc.hpp` (the implementation of the methods of the template class
  `DOFVector<T>`)
Praetorius, Simon's avatar
Praetorius, Simon committed
41

Praetorius, Simon's avatar
Praetorius, Simon committed
42 43 44
Do not use filenames that already exist in /usr/include or are stdandard C/C++ include
files, such as `math.h` (remember that windows files-systems are case insensitive and
thus, there is no difference between `math.h` and `Math.H`.)
Praetorius, Simon's avatar
Praetorius, Simon committed
45 46

## Generale file structure
Praetorius, Simon's avatar
Praetorius, Simon committed
47 48 49
Every header file should start with a copyright notice and an include guard `#pragma once`,
where the text of the copyright notice is given in the file `tools/license.templ.txt`
and can automatically by added, using the script files in the `tools` directory:
Praetorius, Simon's avatar
Praetorius, Simon committed
50 51

``` c++
Praetorius, Simon's avatar
Praetorius, Simon committed
52
// Software License for AMDiS
53
//
54
// Copyright (c) 2015 Institute for Scientific Computing, Technische Universitaet Dresden
Praetorius, Simon's avatar
Praetorius, Simon committed
55 56
// All rights reserved.
// Authors: Simon Praetorius
57
//
Praetorius, Simon's avatar
Praetorius, Simon committed
58
// This file is part of the AMDiS Library
Praetorius, Simon's avatar
Praetorius, Simon committed
59 60 61 62 63
// see also the LICENSE file in the distribution.

#pragma once
```

64
After the include guard a list of include files can be added, see *Names and Order of Includes*.
Praetorius, Simon's avatar
Praetorius, Simon committed
65 66 67

### Names and Order of Includes

Praetorius, Simon's avatar
Praetorius, Simon committed
68 69 70 71
All of a project's header files should be listed as descendants of the project's
source directory. The includes should be grouped following the rules:
* [class header file] ... for source files that implement an interface specified
  in a header file
Praetorius, Simon's avatar
Praetorius, Simon committed
72 73 74 75 76
* C system files.
* C++ system files.
* Other external libraries' header files.
* Your project's header files.

Praetorius, Simon's avatar
Praetorius, Simon committed
77 78 79
For better readability a comment above each group can be added. Within each section
the includes should be ordered alphabetically. Project's header files should be
surrounded by `"`, while external header files should be surrounded by `<...>`.
Praetorius, Simon's avatar
Praetorius, Simon committed
80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105

For example, the includes in `io/VtkWriter.cpp` might look like this:

```c++
#include "io/VtkWriter.hpp"

// [open]mpi header
#ifdef HAVE_PARALLEL_DOMAIN_AMDIS
#include <mpi.h>
#endif

// std c++ headers
#include <cmath>
#include <fstream>
// ...

// boost headers
#include <boost/filesystem/convenience.hpp>
#include <boost/filesystem/operations.hpp>

// AMDiS headers
#include "AdaptInfo.hpp"
#include "DOFVector.hpp"
// ...
```

106
### Namespaces
Praetorius, Simon's avatar
Praetorius, Simon committed
107

Praetorius, Simon's avatar
Praetorius, Simon committed
108 109
All implementation should be put into the namespace `AMDiS`. When a namespace closes,
a corresponding comment should be added to the closing brackets:
Praetorius, Simon's avatar
Praetorius, Simon committed
110 111 112 113 114 115 116 117

``` c++
namespace AMDiS
{
// ...
} // end namespace AMDiS
```

Praetorius, Simon's avatar
Praetorius, Simon committed
118 119 120
Implementation details are put into a subnamespace `Impl`. A few more subnamespaces
of `AMDiS` are allowed, e.g., `Concepts`. If one of these subnamespaces need another
subsubnamespace for implementation details, it should be named `Impl_`.
121

Praetorius, Simon's avatar
Praetorius, Simon committed
122 123
## Line length

124
Each line of text in your code should be at most 100 characters long.
Praetorius, Simon's avatar
Praetorius, Simon committed
125 126

**Exceptions:**
127 128
* An #include statement with a long path may exceed 100 columns.
* A raw-string literal may have content that exceeds 100 characters.
Praetorius, Simon's avatar
Praetorius, Simon committed
129
* ...
130 131 132 133 134 135 136

## Indentation

Use two spaces instead of tabs!

## Documentation

Praetorius, Simon's avatar
Praetorius, Simon committed
137 138
Use Doxygen-Style comments for the documentation of functions and classes, except
when the function name already indicates its meaning completely.