howtos/styleguide.md

+# Style Guide for SHEMAT-Suite `v8.00` #
+
+## Case ##
+
+### Keywords ###
+
+All standard fortran keywords (including all data types and intrinsic functions) are written in lowercase.
+
+**Keywords**
+```fortran
+subroutine, include, implicit none, module, end module,
+allocatable, deallocate, stop, external, call, go to
+```
+**Data types**
+```fortran
+double precision, integer, character, logical
+```
+**Intrinsic functions** 
+```fortran
+max, min, sin
+```
+
+### Functions, clauses, loops ###
+
+
+
+  * `write(...)`, no empty space between `write` and the first parenthesis
+  * `read(...)`, no empty space between `read` and the first parenthesis
+  * `open(...)`, no empty space between `open` and the first parenthesis
+  * `close(...)`, no empty space between `close` and the first parenthesis
+  * `allocate(...)`, no empty space between `allocate` and the first parenthesis
+  * `deallocate(...)`, no empty space between `deallocate` and the first parenthesis
+  * One empty space between `if` and the first parenthesis, three empty spaces below `if`
+  ```fortran
+  if (..) then
+     a=b
+  end if	
+  ```
+  * Three empty spaces below `do`
+  ```fortran
+  do i = 1, n
+    a(i)=b(i)
+  end do
+  ```
+
+## Subroutines and Functions ##
+
+Possibly capitalize first letter to distinguish from arrays.
+```
+subroutine My_sub ()
+```
+
+```
+function My_func ()
+```
+
+## Declaration of variables ##
+
+Best practice: Do not use `kind=4` specification, because it is compiler-dependent.
+
+```fortran
+integer, dimension (3), intent (in) :: i
+integer :: ismpl
+double precision, parameter :: x = 3.0d0
+double precision, intent (out) :: y
+double precision :: z
+logical :: statement
+character (len=20) :: line
+```
+
+Use `::` and one space before and after.
+
+Try to use `intent (in)` and `intent (out)`. Use one whitespace after intent and before the parenthesis. **Exception**: Do not user `intent (in)` or `intent (out)` for the variable `ismpl`. This leads to OpenMP-errors.
+
+In subroutines, first define dummy (input/output) variables, then local variables.
+
+## Loops ##
+
+Try to avoid `exit` or `cycle`.
+
+## Arrays ##
+
+Use brackets, when operating on whole arrays
+
+```
+array(:) = array1(:) + array2(:)
+```
+
+
+## Modules ##
+
+Possibly use `protected` (readable, but not writable outside the module)
+
+## Comments ##
+Use `!`. 
+
+Do **not** use `c`, `C`, or `*`.
+
+`!` is also included in Include-Files.
+
+Two indentations are accepted for comment lines: 
+  * Comment lines starting at Character 1 with `!`
+
+```fortran
+!     if "restart" option is used
+      logical test_option
+      external test_option
+```
+
+  * Comment lines starting with `!` at the indentation of the
+    following line of Fortran code.
+	
+```fortran
+           ! Length of the state vector
+           lstate0 = i0*j0*k0 
+
+```
+
+## Line break ##
+Use `&`.
+
+Do **not** use `+`.
+
+`&` is included at the end of the line that is continued.
+
+## Strings ##
+
+Since Fortran 2003, allocatable strings exist, possibly these could be used in SHEMAT-Suite.
+
+## Code lines ##
+Normal code should only start in the **1st column** (free format,
+fixed format is not necessarily needed).
+
+Try to keep the lines below **80 characters**.
+
+## Comparison operators ##
+
+  * Use `==`, instead of `.eq`
+  * Use `<`, instead of `.lt`
+  * Use `<=`, instead of `.le`
+  * Use `>`, instead of `.gt`
+  * Use `>=`, instead of `.ge`
+  * Use `\=`, instead of `.ne`
+
+## Doxygen headers ##
+
+Example doxygen header:
+
+```fortran
+!>    @author Voker Rath       (ag, rwth aachen)
+!>    @author Andreas Wolf     (sc, rwth aachen)
+!>    @author Darius Mottaghy  (ag, rwth aachen)
+!>    @author Henrik Buesing   (gge, rwth aachen)
+!>    @date 31.08.2012
+!>    @brief main program for forward simulation (only)
+!>    @details
+!>an forward and inverse aquifer simulation tool for coupled flow, heat transfer, and transport (time-dependent)\n
+!>
+!>based on numerical modules developed by: \n
+!> -  Jörn Bartels     (gtn neubrandenburg gmbh)\n
+!> -  Michael Kühn     (tu hamburg-harburg)\n
+!> -  Roland Wagner    (ag,rwth aachen)\n
+!> -  Martin H. Bücker   (sc,rwth aachen)\n
+!> -  Christof Clauser (ag,rwth aachen)\n
+!>    @details
+!> Note: To be able to use input file parsing with hdf5, the
+!> hdf5-input-files have to be generated using the script:
+!> `convert_to_hdf5.py`. This script can be found in the repository
+!> `SHEMAT-Suite_Scripts` under
+!> `python/preprocessing/convert_to_hdf5.py`.
+```
+
+The header should always contain the following fields
+  * `@author`: Authors of the file.
+  * `@date`: Date of the (significant, not documentation, for example)
+    last change
+  * `@brief`: Brief description
+  * `@details`: Detailed description and notes, sources. Should recall
+    the brief description, so that the `html` from doxygen is nicely
+    readable.