|
|
# OpenFOAM C++ Coding Style Guide
|
|
|
|
|
|
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
|
|
|
|
|
|
### General
|
|
|
|
|
|
+ 80 character lines max
|
|
|
+ The normal indentation is 4 __spaces__ per logical level.
|
|
|
+ Use spaces for indentation, not tab characters.
|
|
|
+ Avoid trailing whitespace. It looks ugly and creates spurious file
|
|
|
changes that make it harder notice "real" changes.
|
|
|
+ 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 which returns a thing
|
|
|
// This is a detailed description of the function
|
|
|
// which processes stuff and returns other stuff
|
|
|
// depending on things.
|
|
|
thing function(stuff1, stuff2);
|
|
|
```
|
|
|
Or
|
|
|
```
|
|
|
//- A function which returns a thing, when a particular flow condition is
|
|
|
//- has been satisfied.
|
|
|
// This is a detailed description of the function
|
|
|
// which processes stuff and returns other stuff
|
|
|
// depending on things.
|
|
|
thing function(stuff1, stuff2);
|
|
|
```
|
|
|
|
|
|
+ List entries start with `-` or `-#` for numbered lists but cannot start
|
|
|
on the line immediately below the brief description. Thus an addition
|
|
|
line is required. For example,
|
|
|
|
|
|
```
|
|
|
//- Compare triFaces
|
|
|
// Returns:
|
|
|
// - 0: different
|
|
|
// - +1: identical
|
|
|
// - -1: same face, but different orientation
|
|
|
static int compare(const triFace&, const triFace&);
|
|
|
```
|
|
|
or
|
|
|
```
|
|
|
//- 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/\<VERSION\>/
|
|
|
// <em>for version-specific files</em>
|
|
|
// - ~/.OpenFOAM/
|
|
|
// <em>for version-independent files</em>
|
|
|
// -# group settings
|
|
|
// - $WM_PROJECT_DIR/site/\<VERSION\>
|
|
|
// <em>for version-specific files</em>
|
|
|
// - $WM_PROJECT_DIR/site/
|
|
|
// <em>for version-independent files</em>
|
|
|
// -# other (shipped) settings
|
|
|
// - $WM_PROJECT_DIR/etc/
|
|
|
//
|
|
|
// \return the full path name or fileName() if the name cannot be found
|
|
|
// Optionally abort if the file cannot be found
|
|
|
fileName findEtcFile(const fileName&, bool mandatory=false);
|
|
|
```
|
|
|
|
|
|
For many more details see the
|
|
|
[Doxygen manual](http://doxygen.nl/manual/index.html)
|
|
|
|
|
|
|
|
|
### 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.
|
|
|
+ Reference 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.
|
|
|
+ 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`.
|
|
|
|
|
|
+ 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;
|
|
|
}
|
|
|
```
|
|
|
OR
|
|
|
```
|
|
|
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-base 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. Eg, =++iter= instead of =iter++=
|
|
|
|
|
|
+ `forAll`, `forAllIters`, `forAllConstIters`, /etc./ loops
|
|
|
Like `for` loops, but
|
|
|
```
|
|
|
forAll(
|
|
|
```
|
|
|
*not*
|
|
|
```
|
|
|
forAll (
|
|
|
```
|
|
|
In many cases, the new `forAllIters` and `forAllConstIters` macros
|
|
|
provide a good means of cycling through iterators (when a range-base
|
|
|
for doesn't apply). These use the C++11 decltype and work without
|
|
|
explicitly specifying the container class:
|
|
|
```
|
|
|
forAllIters(myEdgeHash, iter)
|
|
|
```
|
|
|
Using the older `forAllIter` and `forAllConstIter` macros will
|
|
|
still be seen. 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 "="
|
|
|
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.
|
|
|
```
|
|
|
myClass.initialize()
|
|
|
```
|
|
|
|
|
|
#### References
|
|
|
|
|
|
References provided in the `Description` section of the class header files
|
|
|
should be formatted in the [[http://www.apastyle.org][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.
|
|
|
|
|
|
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.
|
|
|
\endverbatim
|
|
|
```
|
|
|
|
|
|
The APA style is a commonly used standard and references are available in
|
|
|
this format from many sources including
|
|
|
[Citation Machine](http://www.citationmachine.net/apa/cite-a-book) and
|
|
|
[Google Scholar]([http://scholar.google.com).
|
|
|
|
|
|
-- |