4_guidelines.tex

\section{Coding 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
\url{http://www.dune-project.org/doc/devel/codingstyle.html}. 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.


\paragraph{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.\\
We 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 \texttt{/** $\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.
Please document freely what each part of your code does. All comments/ documentation
is in \textbf{English}. In particular, please comment \textbf{all}:
\begin{itemize}
  \item Method Parameters (in / out)
  \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 Template Parameters
  \item Return Values
  \item Exceptions thrown by a method
  \item svn-Commits
\end{itemize}

\paragraph{Naming:}
In order to avoid duplicated types or variables a better understanding and usability
of the code we have the following naming principles.
\begin{itemize}
\item \textbf{Variables/Functions\ldots}
  \begin{itemize}
  \item \emph{use} letters and digits
  \item \emph{first letter} is lower case.
  \item \emph{CamelCase}: if your variable names consists of several words, then
        the first letter of each new word should be capital.
  \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 {\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} but \texttt{pressureW} $\rightarrow$ because ``pressure'' is a word.\\
         \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.\\
         \texttt{pcgw} but \texttt{dTauDPi} $\rightarrow$ Both ``Tau'' and ``Pi''
         are words, plus longer than a letter.\\
         \textbf{But:} \texttt{CaCO3} The only exception: chemical formulas are
         written in their chemically correct way $\rightarrow$
  \item \emph{Self-Explaining}: especially abbreviations should be avoided (saturation in stead of S)
  \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}

\paragraph{Exceptions:}
The use of exceptions for error handling is encouraged. Until further notice,
all exceptions thrown are Dune exceptions.

\paragraph{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!