style · Wiki · Development / openfoam

This sets out some guidelines for the coding style in the OpenFOAM code base. As usual, there are no rules without exceptions, but following these guidelines does help people navigating the code and making changes. It also greatly eases the task of integrating community code contributions and enhances long-term maintenance.

Code
Documentation
- General
- Orthography
  - References

Code

General

80 character lines max
The normal indentation is 4 spaces per logical level.
No tab characters - only use spaces for indentation.
No trailing whitespace. It creates spurious file changes that make it difficult to notice real changes (it also looks ugly).
The body of control statements (eg, if, else, while, etc.). are always delineated with braces. A possible exception can be made in conjunction with break or continue as part of a control structure.
The body of case statements is usually delineated with braces.
For stream output, the << operator is always four characters after the start of the stream to ensure that the << symbols align. For example,
```
Info<< ...
os  << ...
```
and
```
WarningInFunction
    << "Warning message"
```
NOT as
```
WarningInFunction
<< "Warning message"
```

Remove unnecessary class section headers. For example, remove

// * * * * * * * * * * * * Private Member Functions  * * * * * * * * * * //

    // Check

    // Edit

    // Write

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

Class titles should be centred

/*-----------------------------------------------------------------------*\
                      Class exampleClass Declaration
\*-----------------------------------------------------------------------*/

NOT

/*-----------------------------------------------------------------------*\
             Class exampleClass Declaration
\*-----------------------------------------------------------------------*/

The .H Header Files

Inline functions
- Use inline functions where appropriate in a separate classNameI.H file. Avoid cluttering the header file with function bodies.
Lines spacing
- Leave two empty lines between sections (as per functions in the .C file etc.)
Use C++ // ... comments in header file to add descriptions to class data and functions do be included in the Doxygen documentation.
- Note that the initial //- tag is special to OpenFOAM for introducing doxygen comments in a compact form.
Destructor
- The destructor is documented with //- like a normal method:
```
//- Destructor
~className();
```

Doxygen documentation in the .H Header Files

When generating documentation with Doxygen, the comments are filtered:

Text on the line starting with //- becomes the Doxygen \brief description.
Subsequent lines that are also start with //- are included as part of the Doxygen \brief description.
Following comment lines (with a plain // ) become the Doxygen detailed description.

Examples:

//- A function that returns a thing
//  This is a detailed description of the function
//  that processes stuff and returns other stuff
//  depending on various things.
thing function(stuff1, stuff2);

//- A function that returns a thing,
//- when a particular flow condition has been satisfied.
//  This is a detailed description of the function
//  that processes stuff and returns other stuff
//  depending on various things.
thing function(stuff1, stuff2);

List entries start with - or -# for numbered lists but cannot start on the line immediately below the brief description. An additional line it thus required. For example,

//- Compare triFaces
//  Returns:
//  -  0: different
//  - +1: identical
//  - -1: same face, but different orientation
static int compare(const triFace&, const triFace&);

//- Compare triFaces returning 0, +1 or -1
//
//  -  0: different
//  - +1: identical
//  - -1: same face, but different orientation
static int compare(const triFace&, const triFace&);

NOT

//- Compare triFaces returning 0, +1 or -1
//  -  0: different
//  - +1: identical
//  - -1: same face, but different orientation
static int compare(const triFace&, const triFace&);

List can be nested as well. For example,

//- Search for \em name
//  in the following hierarchy:
//  -# user settings
//    - ~/.OpenFOAM/\<API\>/
//    - ~/.OpenFOAM/
//  -# group settings
//    - $WM_PROJECT_DIR/site/\<API\>
//    - $WM_PROJECT_DIR/site/
//  -# other (shipped) settings
//    - $WM_PROJECT_DIR/etc/
//
//  \return The full path name of the first file found, or an empty fileName.
fileName findEtcFile(const fileName& name, bool mandatory=false);

For many more details, see the Doxygen manual

The .C Source Files

Use two empty lines between functions

Do not open/close namespaces in a .C file

Fully scope the function name, i.e.

Foam::returnType Foam::className::functionName()

NOT

namespace Foam
{
    ...
    returnType className::functionName()
    ...
}

Exception When there are multiple levels of namespace, they may be used in the .C file to avoid excessive clutter, i.e.

namespace Foam
{
namespace compressible
{
namespace RASModels
{
    ...
} // End namespace RASModels
} // End namespace compressible
} // End namespace Foam

Coding Practice

Passing data as arguments or return values
- Pass bool, label, scalar and other primitive types as copy, anything larger by reference.
Use const everywhere it is applicable.

Initialise references using =

const className& variableName = otherClass.data();

NOT

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

Virtual functions
- If a class is virtual, make all derived classes virtual.
Default constructors
- If the class is not copy constructible or assignable, remove the default generated constructors by marking them as delete.
```
//- No copy construct
className(const className&) = delete;

//- No copy assignment
void operator=(const& className) = delete;
```
It is immaterial if these are marked as delete within private, protected or public, but they are mostly not marked within public for slightly more tidiness.
Default destructor
- If the class easily permits it - all member data types are known within the header, and no special cleanup is required - it is clearer to declare accordingly in the header.
```
//- Destructor
~className() = default;
```

Conditional Statements

if (condition)
{
    code;
}

if
(
   long condition
)
{
    code;
}

NOT (no space between if and ( used)

if(condition)
{
    code;
}

for and while Loops
```
for (i = 0; i < maxI; ++i)
{
    code;
}
```
OR
```
for
(
    i = 0;
    i < maxI;
    ++i
)
{
    code;
}
```
NOT this (no space between for and ( used)
```
for(i = 0; i < maxI; ++i)
{
    code;
}
```
Range-based for should have a space surrounding the ':'
```
for (auto i : range)
{
    code;
}
```
Note that when indexing through iterators, it is often more efficient to use the pre-increment form. That is, ++iter instead of iter++
Macro loops : forAll, forAllIters, forAllConstIters, etc. are like for loops, but without a space. Eg,
```
forAll(
```
NOT
```
forAll (
```
In many cases, the new forAllIters and forAllConstIters macros provide a good means of cycling through iterators (when a range-based for doesn't apply). These use the C++11 decltype and thus work without explicitly specifying the container class:
```
forAllIters(myEdgeHash, iter)
```
Using the older forAllIter and forAllConstIter macros may still be seen (but are generally disappearing). However, since they are macros, they will fail if the iterated object contains any commas. For example, the following will FAIL!:
```
forAllIter(HashTable<labelPair, edge, Hash<edge>>, myEdgeHash, iter)
```
These convenience macros are also generally avoided in other container classes and OpenFOAM primitive classes. In certain cases, the range-based for can also be used.

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.

const Foam::longReturnTypeName&
Foam::longClassName::longFunctionName const

NOT

const Foam::longReturnTypeName&
    Foam::longClassName::longFunctionName const

nor

const Foam::longReturnTypeName& Foam::longClassName::longFunctionName
const

nor

const Foam::longReturnTypeName& Foam::longClassName::
longFunctionName const

If it needs to be split again, split at the function name (leaving behind the preceding scoping ::s), and again, left align, i.e.
```
const Foam::longReturnTypeName&
Foam::veryveryveryverylongClassName::
veryveryveryverylongFunctionName const
```

Splitting long lines at an = sign. Indent after split

variableName =
    longClassName.longFunctionName(longArgument);

OR (where necessary)

variableName =
    longClassName.longFunctionName
    (
        longArgument1,
        longArgument2
    );

NOT

variableName =
longClassName.longFunctionName(longArgument);

NOR

variableName = longClassName.longFunctionName
(
    longArgument1,
    longArgument2
);

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.
```
variableName =
    a*(a + b)
   *exp(c/d)
   *(k + t);
```
  This is sometimes more legible when surrounded by extra parentheses:
```
variableName =
(
    a*(a + b)
   *exp(c/d)
   *(k + t)
);
```
- 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.
```
if
(
    a == true
 && b == c
)
```

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,

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.

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.
```
Class
    Foam::myUnderDocumentedClass

Description
    Foam::myUnderDocumentedClass
```
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.
```
InClass
    Foam::myClass

Description
    Implements the read and writing of files.
```

Doxygen Special Commands

Doxygen has a large number of special commands with a \ prefix.

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

InClass
    Foam::myClass

Description
    Implements the read and writing of files.

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

    Within the implementation, a loop over all patches is done:
    \code
        forAll(patches, patchi)
        {
            ...  // some operation
        }
    \endcode

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. For example,

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 explicitly 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. For example,
```
documented namespace 'Foam::functionEntries' within the
class 'Foam::functionEntry'
```

If nothing else helps, find some sensible header.

namespace 'Foam' is documented in the foamVersion.H file

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 purpose 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

Given the origins of OpenFOAM, the British spellings (eg, neighbour and not neighbor) are generally favoured.

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. Although this particular view may not actually be followed.

myClass.initialize()

References

References provided in the Description section of the class header files should be formatted in the APA (American Psychological Association) style. Example from kEpsilon.H:

Description
    Standard k-epsilon turbulence model for incompressible and compressible
    flows including rapid distortion theory (RDT) based compression term.

    Reference:
    \verbatim
        Standard model:
            Launder, B. E., & Spalding, D. B. (1972).
            Lectures in mathematical models of turbulence.

            Launder, B. E., & Spalding, D. B. (1974).
            The numerical computation of turbulent flows.
            Computer methods in applied mechanics and engineering,
            3(2), 269-289.
            DOI:10.1016/B978-0-08-030937-8.50016-7

        For the RDT-based compression term:
            El Tahry, S. H. (1983).
            k-epsilon equation for compressible reciprocating engine flows.
            Journal of Energy, 7(4), 345-353.
            DOI:10.2514/3.48086
    \endverbatim

The APA style is a commonly used standard and references are available in this format from many sources including Citation Machine and Google Scholar.