Skip to content

Commit 3f94785

Browse files
torbjoernktorbjoernk
committed
first draft of the coding style guide for PFASST
1 parent 1c24566 commit 3f94785

File tree

3 files changed

+320
-0
lines changed

3 files changed

+320
-0
lines changed

‎doc/source/contributing.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Contributing
2+
3+
## Branching and Tagging Model
4+
5+
We use the [git-flow] workflow to that extend, that branch names(paces) have a certain meaing:
6+
7+
Branch Name Pattern | Description
8+
--------------------|-------------
9+
`master` | tip of the `master` branch is always the latest stable release
10+
`development` | tip of the `development` branch is the current state of development and not expected to be stable or even usable
11+
`feature/*` | various feature branches are used to implement new features and should be based off the `development` branch
12+
`release/*` | a release branch is created from the `development` branch and used to prepare a new release and will be merged into `master`
13+
`hotfix/*` | hotfix branches are based off `master` or `development` to fix important and severe bugs and should be merged into `development` and `master` as soon as possible
14+
15+
Releases and release candidates are tagged in the form `release-X.Y.Z(-RCa)`, where `X`, `Y`, and `Z` specify
16+
the version with respect to [semantic versioning] and `a` the number of the release candidate of that version.
17+
18+
19+
## Commit Messages
20+
21+
To ease browsing the proejct's history, we try to keep our commit messages clean and descriptive.
22+
Please try to follow the following rules as best as possible:
23+
24+
* Commit Title must not be longer than 50 characters
25+
26+
If applicable, the title should start with a category name (such as `docu`, `tests`, ...)
27+
followed by a colon (e.g. `"docu: add usage examples for plain SDC"` ).
28+
29+
* Commit Description must have line wraps at 72 characters
30+
31+
* Please *sign* your commits (i.e. use `git commit -s`)
32+
33+
This automatically appends a line of the form `"Signed-off-by: Torbjörn Klatt <[email protected]>"` to the end
34+
of the commit message.
35+
36+
37+
## How to Implement a New Feature?
38+
39+
-# create a fork/clone
40+
-# switch to the `development` branch and pull in the latest changes
41+
-# create a new branch `feature/XYZ` where `XYZ` is a short title of your planned feature
42+
(word seperation should be done with underscores, e.g. `feature/my_awesome_feature`)
43+
-# hack and write Unit Tests
44+
-# commit
45+
-# repeat steps 4 and 5 until you feel your feature is in an almost usable state and most of the unit tests pass
46+
-# write documentation for your feature
47+
-# push your feature branch
48+
-# stay tuned on reviews, remarks and suggestions by the other developers
49+
50+
51+
[git-flow]: http://nvie.com/posts/a-successful-git-branching-model/
52+
[semantic versioning]: http://semver.org/

‎doc/source/style_guide.md‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# Style Guide
2+
3+
To ease development we agree on a basic code style described as follows.
4+
5+
## Naming Convention
6+
7+
In general, abbreviations should only be used if they are absolutely unambigious and would save a
8+
lot of horizontal space.
9+
In case one hesitates whether to abbreviate a variable or not, rather not do it!
10+
11+
Always use underscores (`_`) as word separation.
12+
13+
* __Files__
14+
15+
Due to systems which do not distinguish between upper and lower case in file and path names,
16+
always use lowercase for file names and directories.
17+
18+
Header files should be named after the main/central class contained in.
19+
For example, a class `MyClass` should be in a header file called `my_header.hpp`.
20+
Separate words by underscores.
21+
22+
* __Namespaces__
23+
24+
Should always be lowercase and not too long.
25+
26+
* __Class Names__
27+
28+
Should start with a capital letter and use _CamelCase_.
29+
30+
Abstract classes should start with a capital `I` denoting an _interface_. E.g. `ISweeper` in
31+
`i_sweeper.hpp`.
32+
33+
* __Function Names__
34+
35+
Should only consist of lowercase letters and underscores separating words.
36+
37+
* __Variable Names__
38+
39+
Should always be lowercase using underscores as word separation.
40+
Member variables of classes should start with `m_`.
41+
Constants should all be uppercase with undersocres as word separation.
42+
43+
* __Template Parameter__
44+
45+
In case, most template parameters denote a certain type, append a capital `T` to the name of the
46+
template parameter. E.g.
47+
~~~{.cpp}
48+
template<typename typeT>
49+
int my_func(std::vector<typeT> &vec);
50+
~~~
51+
52+
53+
## Techniques
54+
55+
### Includes
56+
57+
System headers and those from third party libraries should be included using angular brackets.
58+
Headers from our library should be included using double quotes.
59+
60+
For headers included via angular brackets, the preprocessor will search through all paths given via
61+
the `-I` parameter.
62+
While for includes with double quotes it will only look in the directory of the header including
63+
the included file.
64+
Only when there is no such header in there, the preprocessor will go on with the behaviour for
65+
angular brackets.
66+
67+
### Define Guards
68+
69+
Use `#define` guards in header files to prevent multiple inclusion.
70+
The variable defined should be derived from the header file name itself.
71+
For example, a header file `my_header.hpp` in the folder `PFASST/src/subfolder` should have the
72+
following define guard:
73+
74+
~~~{.cpp}
75+
#ifndef PFASST__SUBFOLDER__MY_HEADER_HPP
76+
#define PFASST__SUBFOLDER__MY_HEADER_HPP
77+
// file content
78+
#endif // PFASST__SUBFOLDER__MY_HEADER_HPP
79+
~~~
80+
81+
Always include the library name and at least one subfolder (if applicable) to prevent possible
82+
multiple defines in files with the same name but in different folders.
83+
84+
### Encapsulation / Clean API
85+
86+
We want to provide a clean API, thus we use encapsulation wherever possible.
87+
For classes, we prefer private member/data variables and provide access to them via getter/setter
88+
methods.
89+
90+
### C++ Feature Set
91+
92+
We agreed on using the "most common" C++11 features.
93+
These are:
94+
95+
* `auto` keyword
96+
* `shared_ptr` and `unique_ptr`
97+
* type traits
98+
* static asserts
99+
* Rvalue references and move semantics
100+
* `decltype`
101+
* delegating constructor
102+
* `constexpr`
103+
* right angle bracket (`vector<vector<T> >` vs. `<vector<vector<T>>`)
104+
105+
@todo Check the list of used/required C++11 features and possibly extend it by a list of minimum
106+
compiler versions supporting the features.
107+
108+
109+
## Documentation
110+
111+
Document your code.
112+
113+
We use [Doxygen] for generating the documentation webpage.
114+
You can use pretty much all the features, Doxygen provides, including [MathJAX] for formulas and
115+
[Markdown] for easy text formatting.
116+
117+
118+
## Formatting
119+
120+
In short: no tabs, 2 spaces, sane indent-continuation.
121+
122+
We provide a configuration file for the code beautifier [uncrustify] which does a pretty good job
123+
to ensure consistent formatting of the source files.
124+
125+
126+
[Doxygen]: http://www.stack.nl/~dimitri/doxygen/index.html
127+
[MathJAX]: http://www.stack.nl/~dimitri/doxygen/manual/formulas.html
128+
[Markdown]: http://www.stack.nl/~dimitri/doxygen/manual/markdown.html
129+
[uncrustify]: http://uncrustify.sourceforge.net/

‎format.config.uncrustify.2_spaces‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
indent_align_string=false
2+
indent_braces=false
3+
indent_braces_no_func=false
4+
indent_brace_parent=false
5+
indent_namespace=false
6+
indent_extern=false
7+
indent_class=true
8+
indent_class_colon=false
9+
indent_else_if=false
10+
indent_func_call_param=true
11+
indent_func_def_param=true
12+
indent_func_proto_param=true
13+
indent_func_class_param=true
14+
indent_func_ctor_var_param=true
15+
indent_template_param=true
16+
indent_func_param_double=false
17+
indent_relative_single_line_comments=false
18+
indent_col1_comment=false
19+
indent_access_spec_body=false
20+
indent_paren_nl=false
21+
indent_comma_paren=false
22+
indent_bool_paren=false
23+
indent_square_nl=false
24+
indent_preserve_sql=false
25+
indent_align_assign=true
26+
sp_balance_nested_parens=true
27+
align_keep_tabs=false
28+
align_with_tabs=false
29+
align_on_tabstop=false
30+
align_number_left=false
31+
align_func_params=false
32+
align_same_func_call_params=false
33+
align_var_def_colon=false
34+
align_var_def_attribute=false
35+
align_var_def_inline=false
36+
align_right_cmt_mix=false
37+
align_on_operator=false
38+
align_mix_var_proto=false
39+
align_single_line_func=false
40+
align_single_line_brace=false
41+
align_nl_cont=false
42+
align_left_shift=true
43+
nl_collapse_empty_body=false
44+
nl_assign_leave_one_liners=true
45+
nl_class_leave_one_liners=true
46+
nl_enum_leave_one_liners=true
47+
nl_getset_leave_one_liners=true
48+
nl_func_leave_one_liners=true
49+
nl_if_leave_one_liners=true
50+
nl_multi_line_cond=false
51+
nl_multi_line_define=false
52+
nl_before_case=false
53+
nl_after_case=false
54+
nl_after_return=false
55+
nl_after_semicolon=false
56+
nl_after_brace_open=false
57+
nl_after_brace_open_cmt=false
58+
nl_after_vbrace_open=false
59+
nl_after_brace_close=false
60+
nl_define_macro=false
61+
nl_squeeze_ifdef=false
62+
nl_ds_struct_enum_cmt=false
63+
nl_ds_struct_enum_close_brace=false
64+
nl_create_if_one_liner=false
65+
nl_create_for_one_liner=false
66+
nl_create_while_one_liner=false
67+
ls_for_split_full=false
68+
ls_func_split_full=false
69+
nl_after_multiline_comment=false
70+
eat_blanks_after_open_brace=true
71+
eat_blanks_before_close_brace=true
72+
mod_pawn_semicolon=false
73+
mod_full_paren_if_bool=false
74+
mod_remove_extra_semicolon=false
75+
mod_sort_import=false
76+
mod_sort_using=false
77+
mod_sort_include=false
78+
mod_move_case_break=false
79+
mod_remove_empty_return=false
80+
cmt_indent_multi=true
81+
cmt_c_group=false
82+
cmt_c_nl_start=false
83+
cmt_c_nl_end=false
84+
cmt_cpp_group=false
85+
cmt_cpp_nl_start=false
86+
cmt_cpp_nl_end=false
87+
cmt_cpp_to_c=false
88+
cmt_star_cont=false
89+
cmt_multi_check_last=true
90+
cmt_insert_before_preproc=false
91+
pp_indent_at_level=false
92+
pp_region_indent_code=false
93+
pp_if_indent_code=false
94+
pp_define_at_level=false
95+
indent_columns=2
96+
indent_switch_case=2
97+
nl_max=2
98+
mod_add_long_ifdef_endif_comment=0
99+
mod_add_long_ifdef_else_comment=0
100+
indent_with_tabs=0
101+
sp_before_assign=add
102+
sp_after_assign=add
103+
sp_enum_assign=add
104+
sp_enum_before_assign=add
105+
sp_enum_after_assign=add
106+
sp_pp_concat=add
107+
sp_pp_stringify=add
108+
sp_bool=add
109+
sp_compare=add
110+
sp_inside_paren=add
111+
sp_paren_paren=add
112+
sp_paren_brace=add
113+
sp_template_angle=add
114+
sp_inside_angle=remove
115+
sp_after_angle=add
116+
sp_inside_sparen=add
117+
sp_sparen_brace=add
118+
sp_inside_square=remove
119+
sp_after_comma=add
120+
sp_before_comma=remove
121+
sp_after_class_colon=add
122+
sp_before_class_colon=add
123+
sp_before_case_colon=remove
124+
sp_inside_paren_cast=add
125+
sp_func_def_paren=remove
126+
sp_inside_fparens=remove
127+
sp_inside_fparen=add
128+
sp_square_fparen=remove
129+
sp_fparen_brace=add
130+
sp_func_call_paren=remove
131+
sp_arith=add
132+
sp_assign=add
133+
sp_assign_default=add
134+
sp_enum_assign=add
135+
sp_bool=add
136+
sp_compare=add
137+
nl_namespace_brace=add
138+
nl_class_brace=add
139+
nl_fdef_brace=ignore

0 commit comments

Comments
 (0)