codingStyleGuide.org

#                            -*- mode: org; -*-
#
#+TITLE:                 OpenFOAM C++ style guide
#+AUTHOR:                      OpenCFD Ltd.
#+DATE:                         April 2010
#+LINK:                  http://www.opencfd.co.uk
#+OPTIONS: author:nil ^:{}

* OpenFOAM C++ style guide

*** General
    + 80 character lines max
    + The normal indentation is 4 spaces per logical level.
    + Use spaces for indentation, not tab characters.
    + Avoid trailing whitespace.
    + The body of control statements (eg, if, else, while, etc).
      always delineated with brace brackets. A possible exception can be
      made with 'break' or 'continue' as part of a control structure.

    + stream output
      + =<<= is always four characters after the start of the stream,
        so that the =<<= symbols align, i.e.

#+BEGIN_EXAMPLE
    Info<< ...
    os  << ...
#+END_EXAMPLE

      so

#+BEGIN_EXAMPLE
    WarningIn("className::functionName()")
        << "Warning message"
#+END_EXAMPLE

      NOT

#+BEGIN_EXAMPLE
    WarningIn("className::functionName()")
    << "Warning message"
#+END_EXAMPLE


    + no unnecessary class section headers, i.e. remove

#+BEGIN_EXAMPLE
    // * * * * * * * * * * * * * Private Member Functions  * * * * * * * * * * * //

    // Check

    // Edit

    // Write
#+END_EXAMPLE


      if they contain nothing, even if planned for 'future use'

    + class titles are centred

#+BEGIN_EXAMPLE
    /*---------------------------------------------------------------------------*\
                            Class exampleClass Declaration
    \*---------------------------------------------------------------------------*/
#+END_EXAMPLE

      NOT

#+BEGIN_EXAMPLE
    /*---------------------------------------------------------------------------*\
                Class exampleClass Declaration
    \*---------------------------------------------------------------------------*/
#+END_EXAMPLE

*** The =.H= Files
    + header file spacing
      + Leave two empty lines between sections
        (as per functions in the =.C= file etc)

    + use "//- Comment" comments in header file
      + add descriptions to class data and functions
    + destructor
      + If adding a comment to the destructor -
        use //- and code as a normal function:

#+BEGIN_EXAMPLE
    //- Destructor
    ~className();
#+END_EXAMPLE

    + inline functions
      + Use inline functions where appropriate in a separate classNameI.H file.
        Avoid cluttering the header file with function bodies.

*** The =.C= Files
    + Do not open/close namespaces in a =.C= file
      + Fully scope the function name, i.e.

#+BEGIN_EXAMPLE
    Foam::returnType Foam::className::functionName()
#+END_EXAMPLE

      NOT

#+BEGIN_EXAMPLE
    namespace Foam
    {
        ...
        returnType className::functionName()
        ...
    }
#+END_EXAMPLE

      EXCEPTION

      When there are multiple levels of namespace, they may be used in the =.C=
      file, i.e.

#+BEGIN_EXAMPLE
    namespace Foam
    {
    namespace compressible
    {
    namespace RASModels
    {
        ...
    } // End namespace RASModels
    } // End namespace compressible
    } // End namespace Foam
#+END_EXAMPLE

    + Use two empty lines between functions

*** Coding Practice
    + passing data as arguments or return
      Pass bool, label and scalar as copy, anything larger by reference.

    + const
      Use everywhere it is applicable.

    + variable initialisation using "="

    : const className& variableName = otherClass.data();

      NOT

    : const className& variableName(otherClass.data());

    + virtual functions
      If a class is virtual - make all derived classes virtual.

*** Conditional Statements
#+BEGIN_EXAMPLE
    if (condition)
    {
        code;
    }
#+END_EXAMPLE

    OR

#+BEGIN_EXAMPLE
    if
    (
       long condition
    )
    {
        code;
    }
#+END_EXAMPLE

    NOT (no space between "if" and "(")

#+BEGIN_EXAMPLE
    if(condition)
    {
        code;
    }
#+END_EXAMPLE

*** =for= and =while= Loops

#+BEGIN_EXAMPLE
    for (i = 0; i < maxI; i++)
    {
        code;
    }
#+END_EXAMPLE

    OR

#+BEGIN_EXAMPLE
    for
    (
        i = 0;
        i < maxI;
        i++
    )
    {
        code;
    }
#+END_EXAMPLE

    NOT (no space between "for" and "(")

#+BEGIN_EXAMPLE
    for(i = 0; i < maxI; i++)
    {
        code;
    }
#+END_EXAMPLE

    Note that when indexing through iterators, it is often slightly more
    efficient to use the pre-increment form. Eg, =++iter= instead of =iter++=

*** =forAll=, =forAllIter=, =forAllConstIter=, etc. loops
    like =for= loops, but

#+BEGIN_EXAMPLE
    forAll(
#+END_EXAMPLE

    NOT

#+BEGIN_EXAMPLE
    forAll (
#+END_EXAMPLE

    Using the =forAllIter= and =forAllConstIter= macros is generally
    advantageous - less typing, easier to find later.  However, since
    they are macros, they will fail if the iterated object contains
    any commas.

    The following will FAIL!:

#+BEGIN_EXAMPLE
    forAllIter(HashTable<labelPair, edge, Hash<edge> >, foo, iter)
#+END_EXAMPLE

    These convenience macros are also generally avoided in other
    container classes and OpenFOAM primitive classes.

*** Splitting Over Multiple Lines

**** Splitting return type and function name
     + split initially after the function return type and left align

     + do not put "const" onto its own line - use a split to keep it with
       the function name and arguments.

     so

#+BEGIN_EXAMPLE
     const Foam::longReturnTypeName&
     Foam::longClassName::longFunctionName const
#+END_EXAMPLE

     NOT

#+BEGIN_EXAMPLE
     const Foam::longReturnTypeName&
         Foam::longClassName::longFunctionName const
#+END_EXAMPLE

     NOR

#+BEGIN_EXAMPLE
     const Foam::longReturnTypeName& Foam::longClassName::longFunctionName
     const
#+END_EXAMPLE

     NOR

#+BEGIN_EXAMPLE
     const Foam::longReturnTypeName& Foam::longClassName::
     longFunctionName const
#+END_EXAMPLE

     + if it needs to be split again, split at the function name (leaving
       behind the preceding scoping "::"s), and again, left align, i.e.

     For example,

#+BEGIN_EXAMPLE
     const Foam::longReturnTypeName&
     Foam::veryveryveryverylongClassName::
     veryveryveryverylongFunctionName const
#+END_EXAMPLE

**** Splitting long lines at an "="

     Indent after split

#+BEGIN_EXAMPLE
     variableName =
         longClassName.longFunctionName(longArgument);
#+END_EXAMPLE

     OR (where necessary)

#+BEGIN_EXAMPLE
     variableName =
         longClassName.longFunctionName
         (
             longArgument1,
             longArgument2
         );
#+END_EXAMPLE

     NOT

#+BEGIN_EXAMPLE
     variableName =
     longClassName.longFunctionName(longArgument);
#+END_EXAMPLE

     NOR

#+BEGIN_EXAMPLE
     variableName = longClassName.longFunctionName
     (
         longArgument1,
         longArgument2
     );
#+END_EXAMPLE

*** Maths and Logic
    + operator spacing
      + a + b, a - b
      + a*b, a/b
      + a & b, a ^ b
      + a = b, a != b
      + a < b, a > b, a >= b, a <= b
      + a || b, a && b

    + splitting formulae over several lines

      Split and indent as per "splitting long lines at an "=""
      with the operator on the lower line.  Align operator so that first
      variable, function or bracket on the next line is 4 spaces indented i.e.

#+BEGIN_EXAMPLE
    variableName =
        a * (a + b)
      - exp(c/d)
      * (k + t);
#+END_EXAMPLE

      This is sometime more legible when surrounded by extra parentheses:

#+BEGIN_EXAMPLE
    variableName =
    (
        a * (a + b)
      - exp(c/d)
      * (k + t)
    );
#+END_EXAMPLE

    + splitting logical tests over several lines

      outdent the operator so that the next variable to test is aligned with
      the four space indentation, i.e.

#+BEGIN_EXAMPLE
    if
    (
        a == true
     && b == c
    )
#+END_EXAMPLE

** Documentation

*** General

    + For readability in the comment blocks, certain tags are used that are
      translated by pre-filtering the file before sending it to Doxygen.

    + The tags start in column 1, the contents follow on the next lines and
      indented by 4 spaces. The filter removes the leading 4 spaces from the
      following lines until the next tag that starts in column 1.

    + The 'Class' and 'Description' tags are the most important ones.

    + The first paragraph following the 'Description' will be used for the
      brief description, the remaining paragraphs become the detailed
      description.

      For example,

#+BEGIN_EXAMPLE
    Class
        Foam::myClass

    Description
        A class for specifying the documentation style.

        The class is implemented as a set of recommendations that may
        sometimes be useful.
#+END_EXAMPLE

    + The class name must be qualified by its namespace, otherwise Doxygen
      will think you are documenting some other class.

    + If you don't have anything to say about the class (at the moment), use
      the namespace-qualified class name for the description. This aids with
      finding these under-documented classes later.


#+BEGIN_EXAMPLE
    Class
        Foam::myUnderDocumentedClass

    Description
        Foam::myUnderDocumentedClass
#+END_EXAMPLE


    + Use 'Class' and 'Namespace' tags in the header files.
      The Description block then applies to documenting the class.

    + Use 'InClass' and 'InNamespace' in the source files.
      The Description block then applies to documenting the file itself.


#+BEGIN_EXAMPLE
    InClass
        Foam::myClass

    Description
        Implements the read and writing of files.
#+END_EXAMPLE

*** Doxygen Special Commands

    Doxygen has a large number of special commands with a '\' prefix or a
    (alternatively) an '@' prefix.

    The '@' prefix form is recommended for most Doxygen specials, since it
    has the advantage of standing out. It also happens to be what projects
    like gcc and VTK are using.

    The '\' prefix form, however, looks a bit better for the '\n' newline
    command and when escaping single characters - eg, '\@', '\<', '\>', etc.

    Since the filtering removes the leading 4 spaces within the blocks, the
    Doxygen commmands can be inserted within the block without problems.


#+BEGIN_EXAMPLE
    InClass
        Foam::myClass

    Description
        Implements the read and writing of files.

        An example input file:
        @verbatim
            patchName
            {
                type        myPatchType;
                refValue    100;
                value       uniform 1;
            }
        @endverbatim

        Within the implementation, a loop over all patches is done:
        @code
            forAll(patches, patchI)
            {
                ...  // some operation
            }
        @endcode
#+END_EXAMPLE

*** HTML Special Commands

    Since Doxygen also handles HTML tags to a certain extent, the angle
    brackets need quoting in the documentation blocks. Non-HTML tags cause
    Doxygen to complain, but seem to work anyhow.

    eg,
    + The template with type =<HR>= is a bad example.

    + The template with type =\<HR\>= is a better example.

    + The template with type =<Type>= causes Doxygen to complain about an
      unknown html type, but it seems to work okay anyhow.


*** Documenting Namespaces

    + If namespaces are explictly declared with the =Namespace()= macro,
      they should be documented there.

    + If the namespaces is used to hold sub-models, the namespace can be
      documented in the same file as the class with the model selector.
      eg,

#+BEGIN_EXAMPLE
    documented namespace 'Foam::functionEntries' within the
    class 'Foam::functionEntry'
#+END_EXAMPLE

    + If nothing else helps, find some sensible header.
      eg,

#+BEGIN_EXAMPLE
    namespace 'Foam' is documented in the foamVersion.H file
#+END_EXAMPLE


*** Documenting Typedefs and classes defined via macros

    ... not yet properly resolved


*** Documenting Applications

    Any number of classes might be defined by a particular application, but
    these classes will not, however, be available to other parts of
    OpenFOAM. At the moment, the sole purpuse for running Doxygen on the
    applications is to extract program usage information for the '-doc'
    option.

    The documentation for a particular application is normally contained
    within the first comment block in a =.C= source file. The solution is this
    to invoke a special filter for the "applications/{solver,utilities}"
    directories that only allows the initial comment block for the =.C= files
    through.

    The layout of the application documentation has not yet been finalized,
    but foamToVTK shows an initial attempt.

*** Orthography (an opinion)

    Given the origins of OpenFOAM, the British spellings (eg, neighbour and
    not neighbor) are generally favoured. For code sections that interact
    with external libraries, it can be useful to adopt American spellings,
    especially for names that constitute a significant part of the external
    library - eg, 'color' within graphics sub-systems.

    Both '-ize' and the '-ise' variant are found in the code comments. If
    used as a variable or class method name, it is probably better to use
    '-ize', which is considered the main form by the Oxford University
    Press.

    Eg,
#+BEGIN_EXAMPLE
    myClass.initialize()
#+END_EXAMPLE


    The word "its" (possesive) vs. "it's" (colloquial for "it is" or "it has")
    seems to confuse non-native (and some native) English speakers.
    It is better to donate the extra keystrokes and write "it is" or "it has".
    Any remaining "it's" are likely an incorrect spelling of "its".