Commit c2973437 authored by Bernd Flemisch's avatar Bernd Flemisch
Browse files

Merge branch 'feature/contribution-guide' into 'master'

[doc] Add preliminary contribution guide and style guide

See merge request !992
parents cb9740ba 8e6fe747
# Contribution guidelines for DuMu<sup>x</sup>
DuMu<sup>x</sup> and DUNE are community projects and we are happy about all forms of external contributions.
Here are many easy things that you can do, like
* read the documentation and tell us where and how it should be improved,
* try to install DuMu<sup>x</sup> on your platform and report bugs if it doesn’t work,
* fix bugs and open merge requests or send us patches.
If you decide to contribute code please read this contribution guide.
## Style guide
When contributing code to DuMu<sup>x</sup> please follow the [style guide](doc/styleguide.md). Your work will enjoy much smoother sailing if you stick to it with your changes. DuMu<sup>x</sup> is a pretty large project, and a consistent way of doing things really helps a lot when trying to find your way around the code.
## Contributing
You should get your changes to us in the following way:
* Get an account for our GitLab instance (you might need to contact us if you can't create projects at first login).
* Fork the core module that you want to contribute to, just as you would do on GitHub.
* Push your changes to your fork on some branch.
* Open a merge request using the branch you pushed your changes to as the source branch and the master of the DuMu<sup>x</sup> repository
as the target branch. GitLab will usually ask you about opening a merge request if you browse it right after pushing to some branch.
* Follow the discussion on the merge request to see what improvements should be done to the branch before merging.
* If you have developer status you don't need to do a fork and you can create branches directly.
If you have any questions or complaints about this workflow of contributing to DuMu<sup>x</sup>, please ask on the
[DuMu<sup>x</sup> mailing list](https://listserv.uni-stuttgart.de/mailman/listinfo/dumux).
## Git
* Use Git to your advantage!
* Check out this [great tutorial](https://www.atlassian.com/git/tutorials/setting-up-a-repository) in order to learn how to use it.
* Also check out [Dune's Git best practices](https://www.dune-project.org/doc/guides/git_best_practices/).
* Everything should compile after every single commit.
* Make small commits with changes limited to a single issue / change.
* Format commit messages as follows:
```
[topic] Brief description of the change
Long description containing the status quo,
the changes the commit introduces and why.
```
where `topic` is usually a foldername, `[assembly]`, a model `[2p2c]`, or any other topic, e.g. `[cmake]`.
* Use `git rebase -i master` to update branches to the changes on the master branch.
* Feature branches should be called `feature/my-bla-feature`.
* Bugfix branches should be called `fix/issue-554`.
* Cleanup branches should be called `cleanup/remove-deprecated-bla`.
* Use lower case letters only, and hyphens to separate things.
## GitLab
* Open issues for bugs / discussions / feature requests.
* Give issues a meaningful title, focus each issue on a single topic, describe what the problem is and what you tried.
* Open merge request for changes to be merged into master or other branches. Pushing to master is disabled.
* Give merge requests a meaningful title, describe what the problem is, how this is fixed with this merge request.
* If you don't have the permissions to open branches, you might have permissions to do a fork in your own GitLab namespace and open a merge request from your fork into the dumux repository.
* Merge requests get reviewed by at least one main developer.
* If continuous integration (GitLabCI / BuildBot) is enabled for merge requests, the pipeline has to pass before merging anything to master.
## Patches
* Patches can be supplied via the mailing list,
* should be formatted with git format-patch.
* TODO: How to format patches
......@@ -2,125 +2,5 @@
\label{sc_guidelines}
Writing code in a readable manner is very important, especially
for future code developers (e.g. for adding features, debugging, etc.).
This section is inspired by the DUNE coding guidelines
\url{https://www.dune-project.org/dev/codingstyle/}, which is strongly recommended.
\subsection{Documentation:}
Please document freely what each part of your code \emph{should} do. All comments/documentation
is in English.
We proclaim the Doc-Me Dogma, which means whatever you do, please document
it at least with:
\begin{lstlisting}[style=DumuxCode]
\todo Please doc me!
\end{lstlisting}
That way at least the absence of documentation is documented, and it is easier
to get rid of it systematically.
In the following we will describe several ways for
commenting code in \Dumux.\\
There are four ways to comment a \textbf{single line} of code:
\begin{lstlisting}[style=DumuxCode]
Line of code 1 // Short comment on line of code 1 that will not show in doxygen
Line of code 2 //!< Short comment on line of code 2 that will show in doxygen
//! Short comment on the following line (line of code 3) that will show in doxygen
Line of code 3
/*!
* Longer comment on line of code 4
* with several lines of length
* that will show in doxygen
*/
Line of code 4
\end{lstlisting}
The third and fourth of the above shown options can also be used to document functions with
neither method parameters nor return value.\\
For doxygen to be able to group the \textbf{files} correctly, please add before the headerguard:
\begin{lstlisting}[style=DumuxCode]
/*!
* \file
* \ingroup GroupName
* \brief A short description of the file.
*/
#ifndef HEADERGUARD
#define HEADERGUARD
\end{lstlisting}
For doxygen to be able to group the \textbf{classes} correctly, please add before each class:
\begin{lstlisting}[style=DumuxCode]
/*!
* \ingroup GroupName
* \brief A short description of the class.
*
* Optional detailed description of the class
* over several lines.
*/
template <class TypeTag>
\end{lstlisting}
For an overview over all available groups and to add new groups please
see the file\\ \texttt{doc/doxygen/modules.txt} from the \texttt{dumux} module.\\
Please add before each \textbf{function} with method parameters or return value:
\begin{lstlisting}[style=DumuxCode]
/*!
* \brief A short description of the function.
*
* Optional detailed description of the function
* over several lines.
*
* \param paramName Very short description of paramName
* \return returnName Very short description of returnName
*/
paramType functionName(paramType paramName)
{
...
return returnName
}
\end{lstlisting}
Furthermore, please comment \textit{all}:
\begin{itemize}
\item Template Parameters
\item Exceptions thrown by a method
\item Method parameters which are not self-explanatory should always
have a meaningful comment at calling sites. Example:
\begin{lstlisting}[style=DumuxCode]
localResidual.eval(/*includeBoundaries=*/true);
\end{lstlisting}
\end{itemize}
\subsection{Naming:}
To avoid duplicated types or variables and for a better understanding and usability
of the code we have the following naming conventions:
\begin{itemize}
\item \textbf{Variables/Functions \ldots}
\begin{itemize}
\item start in \emph{lower} case and contain letters.
\item \emph{CamelCase}: if the name consists of several words, then
the first letter of a new word is capital.
\item \emph{Self-Explaining}: in general abbreviations should be avoided (write saturation in stead of S)
\item \emph{Abbreviations}: If and only if a single letter that represents an
abbreviation or index is followed by a single letter (abbreviation or index),
CamelCase is \textbf{not} used. An inner-word underscore is only permitted if
it symbolizes a fraction line. Afterwards, we continue with lower case, i.e.
the common rules apply to both enumerator and denominator. Examples:
\begin{itemize}
\item \texttt{pw} but \texttt{pressureW} $\rightarrow$ because ``pressure'' is a word.
\item \texttt{srnw} but \texttt{sReg} $\rightarrow$ because ``reg'' is not an
abbreviation of a single letter. ``n'' abbreviates ``non'',
``w'' is ``wetting'', so not CamelCase.
\item \texttt{pcgw} but \texttt{dTauDPi} $\rightarrow$ Both ``Tau'' and ``Pi''
are words, plus longer than a letter.
\item \textbf{But:} \texttt{CaCO3} The only exception: chemical formulas are
written in their chemically correct way $\rightarrow$ \texttt{CaCO3}
\end{itemize}
\end{itemize}
\item \textbf{Private Data Variables:} Names of private data variables end with an
underscore and are the only variables that contain underscores.
\item \textbf{Type names:} For type names, the same rules as for variables apply. The
only difference is that the \emph{first letter is capital}.
\item \textbf{Files:} File names should consist of \emph{lower case} letters
exclusively. Header files get the suffix \texttt{.hh}, implementation files the
suffix \texttt{.cc}
\item \textbf{The Exclusive-Access 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. If your header file is called
'myheaderfile.hh', this constant should be DUMUX\_MYHEADERFILE\_HH.
\item \textbf{Macros:} The use of preprocessor macros is strongly discouraged. If you
have to use them for whatever reason, please use capital letters only.
\end{itemize}
For the style guide and instructions how to contribute to \Dumux visit
\url{https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/blob/master/CONTRIBUTING.md}.
# Style guide
This style guide is taken, modified and enhanced from [DUNE](https://dune-project.org/dev/codingstyle/).
## General formatting
* Use 4 spaces indent (no tabs, not 2 spaces).
* _Trailing whitespace_: source files may not contain trailing whitespace to reduce
the amount of noise in diffs and during merges.
* In contrast to the remainder of the coding style guidelines, these code formatting
rules are (partially) enforced automatically with a pre-commit hook. Due to the
distributed nature of Git, this hook can only check your commits once they arrive
in the central repository, so it is important to make your local Git repository check
your commits as well. The dunecontrol script will automatically install such a pre-commit
hook for you.
## C++
### Documentation
* Please document freely what each part of your code _should_ do. Document assumptions.
* All comments/documentation in English.
* We proclaim the Doc-Me dogma, which means whatever you do, please document it at least with
```c++
//! \todo Please doc me!
```
* We use Doxygen to generate documentation from the source code
```c++
int lineOfCode = 1; // Short comment on line of code 1 that will _not_ show in doxygen
int lineOfCode = 2; //!< Short comment on line of code 2 that will show in doxygen
//! Short comment on the following line (line of code 3) that will show in doxygen
int lineOfCode = 3;
/*!
* Longer comment on line of code 4
* with several lines of length
* that will show in doxygen
*/
int lineOfCode = 4;
```
* Files always contain the following documentation header before the headerguard:
```c++
/*!
* \file
* \ingroup GroupName
* \brief A short description of the file.
*/
#ifndef DUMUX_HEADERGUARD_HH
#define DUMUX_HEADERGUARD_HH
```
where `GroupName` is a doxygen module group, click [here](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/blob/master/doc/doxygen/modules.txt) for an overview of existing groups.
* Each class should be documented using the following style:
```c++
/*!
* \ingroup GroupName
* \brief A short description of the class.
*
* Optional detailed description of the class
* over several lines.
*
* \tparam T very short description of the template parameter T
*/
template<class T>
class MyClass {};
```
* Each free function and class member function should be documented using the following style:
```c++
/*!
* \brief A short description of the function.
*
* Optional detailed description of the function
* over several lines.
*
* \tparam paramType Very short description of paramType
* \param paramName Very short description of paramName
* \return returnName Very short description of returnName
*/
template<typename paramType>
paramType functionName(const paramType& paramName)
{
...
return returnName
}
```
* Also document non-obvious function parameters at call site:
```c++
localResidual.eval(/*includeBoundaries=*/true);
```
* Possible exceptions thrown by a function.
### Naming schemes
* Avoid abbreviation, i.e. write `saturation` instead of `s`.
#### Variables / Functions
* CamelCase starting with a lower case letter, each new word starting with a capital letter.
* No underscores (except private data members, see below).
* Exception: If and only if a single letter that represents an
abbreviation or index is followed by a single letter (abbreviation or index),
CamelCase is __not__ used.
* Examples:
- `pw` but `pressureW`, because "pressure" is a word.
- `srnw` but `sReg`, because "Reg" is not an abbreviation consisting of a single letter.
- `pcgw` but `dTauDPi`, because "Tau" and "Pi" are words and longer than one letter.
- `CaCO3`, because we write chemical formulas in their chemically sensible way.
* Private data members end with an underscore.
#### Typenames / Classes / Aliases / Namespaces
* Same rules as for variables, except the first letter is capital.
#### Filenames / Folders
* Lower case letters (filenames, but not foldernames may contain underscores).
* Header files get the suffix `.hh`, implementation files the suffix `.cc`.
* Every header file contains a unique header guard. The name should mimic the folder structure and contain the filename,
i.e. for a file `common/myfile.hh` it should be
```c++
#ifndef DUMUX_COMMON_MYFILE_HH
#define DUMUX_COMMON_MYFILE_HH
```
#### Macros
* The use of preprocessor macros is strongly discouraged. If you have to use them for whatever reason, please use capital letters only.
### Indent
* The default indent is 4 spaces (no tabs, not 2 spaces).
### Formatting
* Curly brackets that open or close a scope are on a separate line (except for [namespaces](#Namespaces)).
* There should be a space between `if`,`else if`,`switch` and the condition.
* `if`,`else if`,`switch` can omit brackets if the expression is only one line.
```c++
// comment for if block, space between if and (enableGravity)
if (enableGravity)
{
Scalar b = 1.0;
return b*gravity_[dimWorld-1];
}
// comment for else-block
else
return 1.0; // ok, one-liner
```
### Namespaces
* Open curly brackets on the same line.
* Do not indent the code inside the namespace.
* Comment closing curly brackets uniquely.
```c++
namespace Dumux {
namespace Properties {
bool here = true;
bool nothere = false; // not like this
} // end namespace Properties
} // end namespace Dumux
```
* Use a `Detail` namespace for hiding implementation details, e.g. for template meta programming.
### Includes
* Space between `#include` and path.
* C++ standard library includes first, then Dune, then others, then DuMu<sup>x</sup>.
* Always use project relative paths.
- Exception: the other header is in the same folder and closely related (`#include "volumevariables.hh"`).
```c++
#include <type_traits>
#include <dune/common/fvector.hh>
#include <dumux/common/exceptions.hh>
```
### Property system
* Prefer class templates with regular template arguments over class templates with a `TypeTag` as template argument.
### Exception
* The use of exceptions for error handling is encouraged.
* There is a variety of DuMu<sup>x</sup> and Dune-specific exceptions you can throw.
* All derive (possibly indirectly) from the class `Dune::Exception` in dune-common.
## Files and folders
* Try to order your new header into the existing directory structure.
* Headers are named like the classes they contain (usually one class per file, exception: closely tied helper classes / functions).
* Headers are named lower case only (using underscores only if absolutely necessary for readability).
* Folder names are lower case only.
* Tests should be called after model and discretization scheme using underscores and lower case only, e.g.
```
test_1p_tpfa
test_2p2c_box_infiltration
```
## CMake
* Use named arguments only.
* TODO
## Python
* TODO
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment