Skip to content
GitLab
Explore
Sign in
Register
Primary navigation
Search or go to…
Project
openfoam
Manage
Activity
Members
Labels
Plan
Issues
Issue boards
Milestones
Wiki
Code
Merge requests
Repository
Branches
Commits
Tags
Repository graph
Compare revisions
Deploy
Releases
Model registry
Analyze
Contributor analytics
Model experiments
Help
Help
Support
GitLab documentation
Compare GitLab plans
Community forum
Contribute to GitLab
Provide feedback
Keyboard shortcuts
?
Snippets
Groups
Projects
Show more breadcrumbs
Development
openfoam
Commits
99b99a46
Commit
99b99a46
authored
10 years ago
by
Henry
Browse files
Options
Downloads
Patches
Plain Diff
codingStyleGuide: Minor updates
parent
71b7d639
Branches
Branches containing commit
Tags
Tags containing commit
No related merge requests found
Changes
1
Hide whitespace changes
Inline
Side-by-side
Showing
1 changed file
doc/codingStyleGuide.org
+49
-78
49 additions, 78 deletions
doc/codingStyleGuide.org
with
49 additions
and
78 deletions
doc/codingStyleGuide.org
+
49
−
78
View file @
99b99a46
# -*- 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
bracket
s. 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'
+
c
lass titles
ar
e centred
+
C
lass titles
should b
e centred
#+BEGIN_SRC C++
/*---------------------------------------------------------------------------*\
Class exampleClass Declaration
\*---------------------------------------------------------------------------*/
#+END_SRC
*not*
#+BEGIN_SRC C++
/*---------------------------------------------------------------------------*\
Class exampleClass Declaration
\*---------------------------------------------------------------------------*/
#+END_SRC
*** The /.H/ Files
+
h
eader file spacing
*** The /.H/
Header
Files
+
H
eader file spacing
+ Leave two empty lines between sections
(as per functions in the /.C/ file etc)
+
u
se =//- Comment= comments in header file to add descriptions to class
(as per functions in the /.C/ file
/
etc
./
)
+
U
se =//- Comment= comments in header file to add descriptions to class
data and functions do be included in the Doxygen documentation:
+
t
ext on the line starting with =//-= becomes the Doxygen brief
+
T
ext on the line starting with =//-= becomes the Doxygen brief
description;
+
t
ext on subsequent lines becomes the Doxygen detailed description /e.g./
+
T
ext 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
+
l
ist entries start with =-= or =-#= for numbered lists but cannot start
+
L
ist 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
+
l
ist can be nested for example
+
L
ist 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
+
f
or more details see the Doxygen documentation.
+
d
estructor
+
If
adding a comment to the destructor
-
use =//-= and code as a normal
function:
+
F
or more details see the Doxygen documentation.
+
D
estructor
+
When
adding a comment to the destructor
use =//-= and code as a normal
function:
#+BEGIN_SRC C++
//- Destructor
~className();
#+END_SRC
+
i
nline functions
+
I
nline 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.
+
v
ariable initialisation using
+
V
ariable 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
+
v
irtual functions
+
V
irtual 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
l
ike =for= loops, but
*** =forAll=, =forAllIter=, =forAllConstIter=,
/
etc.
/
loops
L
ike =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
+
s
plit initially after the function return type and left align
+
d
o not put =const= onto its own line - use a split to keep it with
+
S
plit initially after the function return type and left align
+
D
o 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
+
i
f it needs to be split again, split at the function name (leaving
+
I
f 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
+
o
perator spacing
+
O
perator 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 purp
u
se for running Doxygen on the
OpenFOAM. At the moment, the sole purp
o
se 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".
This diff is collapsed.
Click to expand it.
Preview
0%
Loading
Try again
or
attach a new file
.
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Save comment
Cancel
Please
register
or
sign in
to comment