|
|
<!-- --- title: The OpenFOAM C++ Coding Style Guide -->
|
|
|
|
|
|
[![home](/icons/home.svg "wiki home")](/home)
|
|
|
|
|
|
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.
|
|
|
|
|
|
[[_TOC_]]
|
|
|
|
|
|
## 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);
|
|
|
```
|
|
|
Or
|
|
|
```
|
|
|
//- 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&);
|
|
|
```
|
|
|
_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/\<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](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.
|
|
|
|
|
|
- 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;
|
|
|
}
|
|
|
```
|
|
|
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-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)](http://www.apastyle.org) 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](http://www.citationmachine.net/apa/cite-a-book) and
|
|
|
[Google Scholar]([http://scholar.google.com). |