guidelines.tex

\section{Guidelines} 
\label{guidelines}

An important characteristic of source code is that it is written only
once but usually it is read many times (e.g. when debugging things,
adding features, etc.). For this reason, good programming frameworks
always aim to be as readable as possible, even if comes with higher
effort to write them in the first place. The remainder of this section
is almost a verbatim copy of the DUNE coding guidelines found at
\cite{DUNE-HP}. These guidelines are also recommended for coding with
\Dumux as developer and user.

In order to keep the code maintainable we have decided upon a set of
coding rules.  Some of them may seem like splitting hairs to you, but
they do make it much easier for everybody to work on code that hasn't
been written by oneself.

\begin{itemize}
\item Naming: 
\begin{itemize}
\item Comments: they are helpful! Please document freely what each part of your code does. 
\item all comments / documentation is in English
\item \textbf{Naming Conventions:} Names for variables/functions\ldots \; should only consist of letters and digits. The first
letter should be lower case. If your variable names consists of several words, then 
the first letter of each new word should be capital. \\
If and only if a single letter that represents an abbreviation or index is followed by a single letter (abbreviation or index), CamelCase is {\bf 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: \\
\texttt{pw} vs. \texttt{pressureW} $\rightarrow$ because ``pressure'' is a word.\\
\texttt{srnw} vs. \texttt{sReg} $\rightarrow$ because ``reg'' is not an abbreviation of a single letter. ``n'' abbreviates ``non'', ``w'' is ``wetting'', so not CamelCase.\\
\texttt{pcgw} vs \texttt{dTauDPi} $\rightarrow$ Both ``Tau'' and ``Pi'' are words, plus longer than a letter.\\
The only exception: chemical formulas are written in their chemically correct way $\rightarrow$ \texttt{CaCO3}
\item Variables should be named as self-explaining as possible: especially abbreviations 
should be avoided (saturation in stead of S)
\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}
\item Private Data Variables: Names of private data variables end with an underscore and are the only variables that contain underscores. 
\item Type names: For type names, the same rules as for variables apply. The only difference is that the first letter should be a capital one.
\item Macros: The use of preprocessor macros is strongly discouraged. If you have to use them for whatever reason, please use capital letters only.
\item 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 DUNE\_MYHEADERFILE\_HH.
\item Files: File names should consist of lower case letters exclusively. Header files get the suffix .hh, implementation files the suffix .cc
\end{itemize}
\item Documentation:
      \Dumux, as any software project of similar complexity, will stand and fall with the quality of its documentation.
Therefore it is of paramount importance that you document well everything you do! We use the Doxygen system to extract easily-readable documentation from the source code. Please use its syntax everywhere. In particular, please comment \textbf{all}
\begin{itemize}
\item Method Parameters (in / out)
\item Template Parameters
\item Return Values 
\item Exceptions thrown by a method
 \end{itemize}
     Since we all know that writing documentation is not well-liked and is frequently deferred to some vague 
'next week', we herewith proclaim the Doc-Me Dogma. It goes like this: Whatever you do, and in whatever hurry you 
happen to be, please document everything at least with a {\verb /** $\backslash$todo Please doc me! */}. That way at least the absence 
of documentation is documented, and it is easier to get rid of it systematically.
\item Exceptions:
      The use of exceptions for error handling is encouraged. Until further notice, all exceptions thrown are Dune exceptions.
\item Debugging Code:
      Global debugging code is switched off by setting the macro NDEBUG or the compiler flag -DNDEBUG. In particular, all asserts are 
automatically removed. Use those asserts freely!
\end{itemize}