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

3
Follow the git workflow:
Praetorius, Simon's avatar
Praetorius, Simon committed
4
5
- Create a new branch for all new features, following the naming convention
  `feature/XYZ`
6
- Correct Bugs in issue branches, following the naming convention `issue/XYZ`
7
8
9
10
- For features and issues *Merge Request* into the master branch should be created in GitLab
- Do not push into `master` directly
- Releases are created in a new branch `release/VERSION` that is not deleted after merged into master.
  After the merge, a tag with name `vVERSION` should be created.
11

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

Praetorius, Simon's avatar
Praetorius, Simon committed
14
15
16
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
17

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

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

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

Praetorius, Simon's avatar
Praetorius, Simon committed
25
26
27
28
29
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
30
31
32
33
34
35
36
37

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
38
39
* `DOFVector.inc.hpp` (the implementation of the methods of the template class
  `DOFVector<T>`)
Praetorius, Simon's avatar
Praetorius, Simon committed
40

Praetorius, Simon's avatar
Praetorius, Simon committed
41
42
43
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
44
45
46
47
48

## Generale file structure

### Names and Order of Includes

Praetorius, Simon's avatar
Praetorius, Simon committed
49
50
51
52
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
53
54
55
56
57
* C system files.
* C++ system files.
* Other external libraries' header files.
* Your project's header files.

Praetorius, Simon's avatar
Praetorius, Simon committed
58
59
60
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
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

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

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

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

// 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"
// ...
```

85
### Namespaces
Praetorius, Simon's avatar
Praetorius, Simon committed
86

Praetorius, Simon's avatar
Praetorius, Simon committed
87
88
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
89
90
91
92
93
94
95
96

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

Praetorius, Simon's avatar
Praetorius, Simon committed
97
98
99
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_`.
100

Praetorius, Simon's avatar
Praetorius, Simon committed
101
## Formatting
Praetorius, Simon's avatar
Praetorius, Simon committed
102

Praetorius, Simon's avatar
Praetorius, Simon committed
103
### Line length
104
Each line of text in your code should be at most 100 characters long.
Praetorius, Simon's avatar
Praetorius, Simon committed
105
106

**Exceptions:**
107
108
* 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
109
* ...
110

Praetorius, Simon's avatar
Praetorius, Simon committed
111
112
### Indentation
Use two spaces instead of tabs! Follow the formatting rules of the K&R style.
113

Praetorius, Simon's avatar
Praetorius, Simon committed
114
115
116
117
118
119
120
121
122
### Variable qualifiers
Use trailing `const`/`volatile` qualifiers for variables, e.g.

```c++
double const& d_ref = d;
```

### Functions
Try to put all parameters in the line of the function declaration until it exceeds
123
the maximum line length. Then list remaining arguments aligned with the first
Praetorius, Simon's avatar
Praetorius, Simon committed
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
function argument.  Follow the style of the brackets, like

```c++
return_type function_name(Arg1 arg1, LongArgumentType longArgumentName,
                          Arg3 argument3)
{
  // implementation of the function
}
```

### Classes
Put base-classes on a new line, do not indent labels, member variables are appended
with an underscore and follow the other formatting rules in the followign example:

```c++
template <class Type>
class SubClass
    : public BaseClass
{
public:
  SubClass(Arg1 arg1, Arg2 arg2)
    : member1_(arg1)
    , member2_(arg2)
  {}
148

Praetorius, Simon's avatar
Praetorius, Simon committed
149
150
151
152
153
private:
  Arg1 member1_;
  Arg2 member2_;
};
```
154
155
156

## Documentation

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