codingStyleGuide: Minor updates

doc/codingStyleGuide.org

@@ -1,9 +1,9 @@
 #                            -*- mode: org; -*-
 #
-#+TITLE:               OpenFOAM C++ style guide
+#+TITLE:                 OpenFOAM C++ style guide
-#+AUTHOR:                      OpenFOAM Foundation
+#+AUTHOR:                  OpenFOAM Foundation
-#+DATE:                             Aug 2011
+#+DATE:                       Aug 2011-2015
-#+LINK:                     http://www.OpenFOAM.org
+#+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
+    + The body of control statements (eg, =if=, =else=, =while=, /etc./). is
-      always delineated with brace brackets. A possible exception can be
+      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.
+    + The body of =case= statements is usually delineated with braces.
-    + A fall-through =case= should be commented as such.
+    + Stream output
-
-    + 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
+*** The /.H/ Header Files
-    + header file spacing
+    + Header file spacing
       + Leave two empty lines between sections
-        (as per functions in the /.C/ file etc)
+        (as per functions in the /.C/ file /etc./)
-    + use =//- Comment= comments in header file to add descriptions to class
+    + 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.
+      + For more details see the Doxygen documentation.
-    + destructor
+    + Destructor
-      + If adding a comment to the destructor -
+      + When adding a comment to the destructor use =//-= and code as a normal
-        use =//-= and code as a normal function:
+        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.
+    + Passing data as arguments or return values:
-      + Pass bool, label and scalar as copy, anything larger by reference.
+      + Pass bool, label, scalar and other primitive types as copy,
-    + const
+        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
+*** =forAll=, =forAllIter=, =forAllConstIter=, /etc./ loops
-    like =for= loops, but
+    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.
+    any commas /e.g./ following will FAIL!:
-
-    The 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
+      + 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
+      + 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.
+      description.  For example,
-
-      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.
+    Doxygen to complain, but seem to work anyhow.  /e.g./,
-
-    eg,
     + 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
+    Given the origins of OpenFOAM, the British spellings (/e.g./, neighbour and
-    neighbor) are generally favoured.
+    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".