... | ... | @@ -12,6 +12,35 @@ code contributions and enhances long-term maintenance. |
|
|
|
|
|
## Code
|
|
|
|
|
|
### Header Guards
|
|
|
|
|
|
OpenFOAM uses traditional header guards instead of the (non-standard
|
|
|
but widely supported) `#prama once` directive.
|
|
|
This is largely historical, but in some minor cases the header guards
|
|
|
are also used to manually resolve cyclic include dependencies.
|
|
|
|
|
|
One of the *odd* features of OpenFOAM is its handling of templated code.
|
|
|
Inclusion of template files is typically surrounded by a
|
|
|
`#ifdef NoRepository` block:
|
|
|
```
|
|
|
#ifdef NoRepository
|
|
|
#include "UList.C"
|
|
|
#include "UListIO.C"
|
|
|
#endif
|
|
|
```
|
|
|
This is largely a holdover from earlier C++ compilers and their
|
|
|
handling of inlined or separately/pre-compiled templates. This idiom
|
|
|
is still retained in large parts of the code (in the hope that it may
|
|
|
again prove useful). It does however mean that most OpenFOAM
|
|
|
code must be compiled with `-DNoRepository` defined (as is done
|
|
|
in the *wmake* rules).
|
|
|
|
|
|
|
|
|
To avoid name clashes, newer header guards use `Foam_` in their names.
|
|
|
Header guards with `FoamCompat_` in their name indicate a compatibility
|
|
|
header, which may or may not be slated for removal in the future.
|
|
|
|
|
|
|
|
|
### General
|
|
|
|
|
|
- 80 character lines max
|
... | ... | @@ -72,7 +101,7 @@ code contributions and enhances long-term maintenance. |
|
|
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.)
|
|
|
(as per functions in the _.cxx_ 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
|
... | ... | @@ -163,10 +192,10 @@ For many more details, see the |
|
|
[Doxygen manual](http://doxygen.nl/manual/index.html)
|
|
|
|
|
|
|
|
|
### The _.C_ Source Files
|
|
|
### Source Files (_.C_, _.cxx_, ...)
|
|
|
|
|
|
- Use two empty lines between functions
|
|
|
- Do not open/close namespaces in a _.C_ file
|
|
|
- Do not open/close namespaces in a source file
|
|
|
- Fully scope the function name, i.e.
|
|
|
```
|
|
|
Foam::returnType Foam::className::functionName()
|
... | ... | @@ -182,7 +211,7 @@ For many more details, see the |
|
|
```
|
|
|
_Exception_
|
|
|
When there are multiple levels of namespace, they may be used in the
|
|
|
_.C_ file to avoid excessive clutter, i.e.
|
|
|
source file to avoid excessive clutter, i.e.
|
|
|
```
|
|
|
namespace Foam
|
|
|
{
|
... | ... | @@ -294,7 +323,7 @@ For many more details, see the |
|
|
```
|
|
|
Range-based for should have a space surrounding the ':'
|
|
|
```
|
|
|
for (auto i : range)
|
|
|
for (const auto& item : range)
|
|
|
{
|
|
|
code;
|
|
|
}
|
... | ... | @@ -549,9 +578,9 @@ 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
|
|
|
within the first comment block in a 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
|
|
|
directories that only allows the initial comment block for the source files
|
|
|
through.
|
|
|
|
|
|
The layout of the application documentation has not yet been finalized,
|
... | ... | @@ -610,4 +639,4 @@ this format from many sources including |
|
|
|
|
|
----
|
|
|
|
|
|
Copyright (C) 2019-2020 OpenCFD Ltd. |
|
|
Copyright (C) 2019-2023 OpenCFD Ltd. |