From 513f7d51bb1b4dab7a4ca7472178551a86fae28d Mon Sep 17 00:00:00 2001
From: Timo Koch <timo.koch@iws.uni-stuttgart.de>
Date: Wed, 25 Jul 2018 12:20:47 +0200
Subject: [PATCH] [styleguide] Add content from dumux handbook

---
 doc/styleguide.md | 176 ++++++++++++++++++++++++++++++++++------------
 1 file changed, 132 insertions(+), 44 deletions(-)

diff --git a/doc/styleguide.md b/doc/styleguide.md
index 5e01b0a5b9..43fed36960 100644
--- a/doc/styleguide.md
+++ b/doc/styleguide.md
@@ -1,20 +1,122 @@
 # Style guide
 
-## File system
+## C++
 
-* 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 names 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.
+### Documentation
 
-__Example:__
-```
-test_1p_tpfa
-test_2p2c_box_infiltration
-```
+* 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. `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 of a single letter
+    - `pcgw` but `dTauDPi`, because "Tau" and "Pi" are words and longer than a 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.
 
-## C++
 
 ### Indent
 
@@ -56,6 +158,7 @@ bool here = true;
 } // end namespace Properties
 } // end namespace Dumux
 ```
+* Use a `Detail` namespace for hiding implementation details, e.g. for template meta programming
 
 ### Includes
 
@@ -70,44 +173,29 @@ bool here = true;
 #include <dumux/common/exceptions.hh>
 ```
 
-### Documentation
-
-* Prefer long-style doxygen documentation of the form
-* at least containing a `\brief`
-
-```c++
-/*
- * \brief Base class for all linear solvers
- */
-```
-
-* document all parameters of functions and what it returns
-* optionally document which error the function might throw
-
-### Classes
-
-TODO
+### Property system
 
-#### Member functions
+* Prefer class templates with regular template arguments over class templates with a `TypeTag` as template argument
 
-TODO
+## Files and folders
 
-#### Private data member
-* Use underscore postfix
+* 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.
 
-```c++
-...
-private:
-    int steps_;
-...
+__Example:__
+```
+test_1p_tpfa
+test_2p2c_box_infiltration
 ```
 
-### Functions
-
-TODO
+## CMake
 
-### Property system
+* Use named arguments only
+* TODO
 
-* Prefer class templates with regular template arguments over class templates with a `TypeTag` as template argument
+## Python
 
-TODO
+* TODO
-- 
GitLab