diff --git a/doc/codingStyleGuide.org b/doc/codingStyleGuide.org
index a6e8208e0ad8f7e8a59a2af5c81fc035b9eb6be4..e61a00d7d2848b8b1effcb6211a49d1dfb141f3a 100644
--- a/doc/codingStyleGuide.org
+++ b/doc/codingStyleGuide.org
@@ -1,9 +1,9 @@
# -*- mode: org; -*-
#
-#+TITLE: OpenFOAM C++ style guide
-#+AUTHOR: OpenFOAM Foundation
-#+DATE: Aug 2011
-#+LINK: http://www.OpenFOAM.org
+#+TITLE: OpenFOAM C++ style guide
+#+AUTHOR: OpenFOAM Foundation
+#+DATE: Aug 2011-2015
+#+LINK: http://www.OpenFOAM.org
#+OPTIONS: author:nil ^:{}
#+STARTUP: hidestars
#+STARTUP: odd
@@ -14,14 +14,12 @@
+ 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). is
- always delineated with brace brackets. A possible exception can be
+ + The body of control statements (eg, =if=, =else=, =while=, /etc./). is
+ 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 brace brackets.
- + A fall-through =case= should be commented as such.
-
- + stream output
+ + The body of =case= statements is usually delineated with braces.
+ + Stream output
+ =<<= is always four characters after the start of the stream,
so that the =<<= symbols align, i.e.
#+BEGIN_SRC c++
@@ -39,7 +37,7 @@
<< "Warning message"
#+END_SRC
- + no unnecessary class section headers, i.e. remove
+ + Remove unnecessary class section headers, i.e. remove
#+BEGIN_SRC C++
// * * * * * * * * * * * * * Private Member Functions * * * * * * * * * * * //
@@ -51,30 +49,28 @@
#+END_SRC
if they contain nothing, even if planned for 'future use'
- + class titles are centred
+ + Class titles should be centred
#+BEGIN_SRC C++
/*---------------------------------------------------------------------------*\
Class exampleClass Declaration
\*---------------------------------------------------------------------------*/
#+END_SRC
-
*not*
-
#+BEGIN_SRC C++
/*---------------------------------------------------------------------------*\
Class exampleClass Declaration
\*---------------------------------------------------------------------------*/
#+END_SRC
-*** The /.H/ Files
- + header file spacing
+*** The /.H/ Header Files
+ + Header file spacing
+ Leave two empty lines between sections
- (as per functions in the /.C/ file etc)
- + use =//- Comment= comments in header file to add descriptions to class
+ (as per functions in the /.C/ file /etc./)
+ + Use =//- Comment= comments in header file to add descriptions to class
data and functions do be included in the Doxygen documentation:
- + text on the line starting with =//-= becomes the Doxygen brief
+ + Text on the line starting with =//-= becomes the Doxygen brief
description;
- + text on subsequent lines becomes the Doxygen detailed description /e.g./
+ + Text on subsequent lines becomes the Doxygen detailed description /e.g./
#+BEGIN_SRC C++
//- A function which returns a thing
// This is a detailed description of the function
@@ -82,7 +78,7 @@
// depending on things.
thing function(stuff1, stuff2);
#+END_SRC
- + list entries start with =-= or =-#= for numbered lists but cannot start
+ + List entries start with =-= or =-#= for numbered lists but cannot start
on the line immediately below the brief description so
#+BEGIN_SRC C++
//- Compare triFaces
@@ -109,7 +105,7 @@
// - -1: same face, but different orientation
static inline int compare(const triFace&, const triFace&);
#+END_SRC
- + list can be nested for example
+ + List can be nested for example
#+BEGIN_SRC C++
//- Search for \em name
// in the following hierarchy:
@@ -130,19 +126,19 @@
// Optionally abort if the file cannot be found
fileName findEtcFile(const fileName&, bool mandatory=false);
#+END_SRC
- + for more details see the Doxygen documentation.
- + destructor
- + If adding a comment to the destructor -
- use =//-= and code as a normal function:
+ + For more details see the Doxygen documentation.
+ + Destructor
+ + When adding a comment to the destructor use =//-= and code as a normal
+ function:
#+BEGIN_SRC C++
//- Destructor
~className();
#+END_SRC
- + inline functions
+ + Inline functions
+ Use inline functions where appropriate in a separate /classNameI.H/
file. Avoid cluttering the header file with function bodies.
-*** The /.C/ Files
+*** The /.C/ Sourcs Files
+ Do not open/close namespaces in a /.C/ file
+ Fully scope the function name, i.e.
#+BEGIN_SRC C++
@@ -157,10 +153,9 @@
...
}
#+END_SRC
- EXCEPTION
-
+ *Exception*
When there are multiple levels of namespace, they may be used in the
- /.C/ file, i.e.
+ /.C/ file to avoid excessive clutter, i.e.
#+BEGIN_SRC C++
namespace Foam
{
@@ -177,11 +172,12 @@
+ Use two empty lines between functions
*** Coding Practice
- + passing data as arguments or return values.
- + Pass bool, label and scalar as copy, anything larger by reference.
- + const
+ + Passing data as arguments or return values:
+ + Pass bool, label, scalar and other primitive types as copy,
+ anything larger by reference.
+ + =const=
+ Use everywhere it is applicable.
- + variable initialisation using
+ + Variable initialisation using
#+BEGIN_SRC C++
const className& variableName = otherClass.data();
#+END_SRC
@@ -189,7 +185,7 @@
#+BEGIN_SRC C++
const className& variableName(otherClass.data());
#+END_SRC
- + virtual functions
+ + Virtual functions
+ If a class is virtual, make all derived classes virtual.
*** Conditional Statements
@@ -246,8 +242,8 @@
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
+*** =forAll=, =forAllIter=, =forAllConstIter=, /etc./ loops
+ Like =for= loops, but
#+BEGIN_SRC C++
forAll(
#+END_SRC
@@ -258,10 +254,7 @@
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!:
-
+ any commas /e.g./ following will FAIL!:
#+BEGIN_SRC C++
forAllIter(HashTable<labelPair, edge, Hash<edge> >, foo, iter)
#+END_SRC
@@ -270,8 +263,8 @@
*** 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
+ + 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.
#+BEGIN_SRC C++
const Foam::longReturnTypeName&
@@ -292,7 +285,7 @@
const Foam::longReturnTypeName& Foam::longClassName::
longFunctionName const
#+END_SRC
- + if it needs to be split again, split at the function name (leaving
+ + If it needs to be split again, split at the function name (leaving
behind the preceding scoping =::=s), and again, left align, i.e.
#+BEGIN_SRC C++
const Foam::longReturnTypeName&
@@ -330,7 +323,7 @@
#+END_SRC
*** Maths and Logic
- + operator spacing
+ + Operator spacing
#+BEGIN_SRC C++
a + b, a - b
a*b, a/b
@@ -339,8 +332,7 @@
a < b, a > b, a >= b, a <= b
a || b, a && b
#+END_SRC
-
- + splitting formulae over several lines
+ + 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
@@ -361,8 +353,7 @@
*(k + t)
);
#+END_SRC
-
- + splitting logical tests over several lines
+ + 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.
@@ -378,18 +369,13 @@
*** 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,
+ description. For example,
#+BEGIN_SRC C++
Class
Foam::myClass
@@ -403,7 +389,6 @@
+ 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.
@@ -414,10 +399,8 @@
Description
Foam::myUnderDocumentedClass
#+END_SRC
-
+ 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_SRC C++
@@ -462,9 +445,7 @@
*** 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,
+ Doxygen to complain, but seem to work anyhow. /e.g./,
+ 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
@@ -473,28 +454,23 @@
*** 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,
+ /e.g./,
#+BEGIN_SRC C++
documented namespace 'Foam::functionEntries' within the
class 'Foam::functionEntry'
#+END_SRC
-
+ If nothing else helps, find some sensible header.
- eg,
+ /e.g./,
#+BEGIN_SRC C++
namespace 'Foam' is documented in the foamVersion.H file
#+END_SRC
-*** 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
+ OpenFOAM. At the moment, the sole purpose for running Doxygen on the
applications is to extract program usage information for the '-doc'
option.
@@ -508,18 +484,13 @@
but foamToVTK shows an initial attempt.
*** Orthography
- Given the origins of OpenFOAM, the British spellings (eg, neighbour and not
- neighbor) are generally favoured.
+ Given the origins of OpenFOAM, the British spellings (/e.g./, 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. Eg,
+ Press. /e.g./,
#+BEGIN_SRC C++
myClass.initialize()
#+END_SRC
-
- 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".