Skip to content
Snippets Groups Projects
Commit 6f148092 authored by Mark Olesen's avatar Mark Olesen
Browse files

Copy some of GUIDELINES -> codingStyleGuide.org 

- use ':' to prefix verbatim code instead of #+BEGIN_EXAMPLE / #+END_EXAMPLE
  for a somewhat better feeling for the indentation.
parent fa93ce8c
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
doc/GUIDELINES
+ 2
− 2
View file @ 6f148092
...@@ -109,7 +109,7 @@ eg, ...@@ -109,7 +109,7 @@ eg,
| |
| Within the implementation, a loop over all patches is done: | Within the implementation, a loop over all patches is done:
| @code | @code
| forAll (patches, patchI) | forAll(patches, patchI)
| { | {
| ... // some operation | ... // some operation
| } | }
...@@ -222,4 +222,4 @@ The doc/Doxygen/tools directory contains miscellaneous scripts for finding ...@@ -222,4 +222,4 @@ The doc/Doxygen/tools directory contains miscellaneous scripts for finding
and possibly repairing documentation issues. and possibly repairing documentation issues.
Updated: 2008-03-17 Updated: 2009-11-27
doc/codingStyleGuide.org
+ 321
− 202
View file @ 6f148092
...@@ -17,292 +17,244 @@ ...@@ -17,292 +17,244 @@
+ Avoid trailing whitespace. + Avoid trailing whitespace.
+ stream output + stream output
<< is always four characters after the start of the stream, =<<= is always four characters after the start of the stream,
so that the << symbols align, i.e. so that the =<<= symbols align, i.e.
#+BEGIN_EXAMPLE :Info<< ...
Info<< ... :os << ...
os << ...
#+END_EXAMPLE
so so
#+BEGIN_EXAMPLE :WarningIn("className::functionName()")
WarningIn("className::functionName()") : << "Warning message"
<< "Warning message"
#+END_EXAMPLE
NOT NOT
#+BEGIN_EXAMPLE :WarningIn("className::functionName()")
WarningIn("className::functionName()") :<< "Warning message"
<< "Warning message"
#+END_EXAMPLE
+ no unnecessary class section headers, i.e. remove
#+BEGIN_EXAMPLE
// * * * * * * * * * * * * * Private Member Functions * * * * * * * * * * * //
// Check
// Edit + no unnecessary class section headers, i.e. remove
// Write :// * * * * * * * * * * * * * Private Member Functions * * * * * * * * * * * //
#+END_EXAMPLE :
:// Check
:
:// Edit
:
:// Write
if they contain nothing, even if planned for 'future use' if they contain nothing, even if planned for 'future use'
+ class titles are centred + class titles are centred
#+BEGIN_EXAMPLE :/*---------------------------------------------------------------------------*\
/*---------------------------------------------------------------------------*\ : Class exampleClass Declaration
Class exampleClass Declaration :\*---------------------------------------------------------------------------*/
\*---------------------------------------------------------------------------*/
#+END_EXAMPLE
NOT NOT
#+BEGIN_EXAMPLE :/*---------------------------------------------------------------------------*\
/*---------------------------------------------------------------------------*\ : Class exampleClass Declaration
Class exampleClass Declaration :\*---------------------------------------------------------------------------*/
\*---------------------------------------------------------------------------*/
#+END_EXAMPLE
*** .H Files *** The =.H= Files
+ header file spacing + header file spacing
Leave two empty lines between sections (as per functions in the .C file etc) Leave two empty lines between sections (as per functions in the =.C= file etc)
+ use "//- Comment" comments in header file + use "//- Comment" comments in header file
+ add descriptions to class data and functions + add descriptions to class data and functions
+ destructor + destructor
If adding a comment to the destructor - use //- and code as a normal function: If adding a comment to the destructor - use //- and code as a normal function:
#+BEGIN_EXAMPLE ://- Destructor
//- Destructor :~className();
~className();
#+END_EXAMPLE
+ inline functions + inline functions
Use inline functions where appropriate in a separate classNameI.H file. Use inline functions where appropriate in a separate classNameI.H file.
Avoid cluttering the header file with function bodies. Avoid cluttering the header file with function bodies.
*** .C Files *** The =.C= Files
+ Do not open/close namespaces in a .C file + Do not open/close namespaces in a =.C= file
Fully scope the function name, i.e. Fully scope the function name, i.e.
#+BEGIN_EXAMPLE :Foam::returnType Foam::className::functionName()
Foam::returnType Foam::className::functionName()
#+END_EXAMPLE
NOT NOT
#+BEGIN_EXAMPLE :namespace Foam
namespace Foam :{
{ : ...
... :
: returnType className::functionName()
returnType className::functionName() :
: ...
... :}
}
#+END_EXAMPLE
EXCEPTION EXCEPTION
When there are multiple levels of namespace, they may be used in the .C When there are multiple levels of namespace, they may be used in the =.C=
file, i.e. file, i.e.
#+BEGIN_EXAMPLE :namespace Foam
namespace Foam :{
{ :namespace compressible
namespace compressible :{
{ :namespace RASModels
namespace RASModels :{
{ :
: ...
... :
:} // End namespace RASModels
} // End namespace RASModels :} // End namespace compressible
} // End namespace compressible :} // End namespace Foam
} // End namespace Foam
#+END_EXAMPLE
+ Use two empty lines between functions + Use two empty lines between functions
*** Coding Practise *** Coding Practice
+ passing data as arguments or return + passing data as arguments or return
Pass bool, label and scalar as copy, anything larger by reference. Pass bool, label and scalar as copy, anything larger by reference.
+ const + const
Use everywhere it is applicable. Use everywhere it is applicable.
+ variable initialisation using "=" + variable initialisation using "="
#+BEGIN_EXAMPLE : const className& variableName = otherClass.data();
const className& variableName = otherClass.data();
#+END_EXAMPLE
NOT NOT
#+BEGIN_EXAMPLE : const className& variableName(otherClass.data());
const className& variableName(otherClass.data());
#+END_EXAMPLE
+ virtual functions + virtual functions
If a class is virtual - make all derived classes virtual. If a class is virtual - make all derived classes virtual.
*** Conditional Statements *** Conditional Statements
#+BEGIN_EXAMPLE :if (condition)
if (condition) :{
{ : code;
code; :}
}
#+END_EXAMPLE
OR OR
#+BEGIN_EXAMPLE :if
if :(
( : long condition
long condition :)
) :{
{ : code;
code; :}
}
#+END_EXAMPLE
NOT (no space between "if" and "(") NOT (no space between "if" and "(")
#+BEGIN_EXAMPLE :if(condition)
if(condition) :{
{ : code;
code; :}
}
#+END_EXAMPLE *** =for= Loops
:for (i = 0; i < maxI; i++)
*** `for' Loops :{
#+BEGIN_EXAMPLE : code;
for (i = 0; i < maxI; i++) :}
{
code;
}
#+END_EXAMPLE
OR OR
#+BEGIN_EXAMPLE :for
for :(
( : i = 0;
i = 0; : i < maxI;
i < maxI; : i++
i++ :)
) :{
{ : code;
code; :}
}
#+END_EXAMPLE
NOT (no space between "for" and "(") NOT (no space between "for" and "(")
#+BEGIN_EXAMPLE :for(i = 0; i < maxI; i++)
for(i = 0; i < maxI; i++) :{
{ : code;
code; :}
}
#+END_EXAMPLE Note that when indexing through iterators, it is often slightly more
efficient to use the pre-increment form. Eg, =++iter= instead of =iter++=
*** `forAll' loops *** =forAll= loops
like for loops, but like =for= loops, but
#+BEGIN_EXAMPLE :forAll(
forAll(
#+END_EXAMPLE
NOT NOT
#+BEGIN_EXAMPLE :forAll (
forAll (
#+END_EXAMPLE
*** Splitting Over Multiple Lines *** Splitting Over Multiple Lines
+ splitting return type and function name
**** 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 the + do not put "const" onto its own line - use a split to keep it with
function name and arguments. the function name and arguments.
so: so:
#+BEGIN_EXAMPLE :const Foam::longReturnTypeName&
const Foam::longReturnTypeName& :Foam::longClassName::longFunctionName const
Foam::longClassName::longFunctionName const
#+END_EXAMPLE
NOT NOT
#+BEGIN_EXAMPLE :const Foam::longReturnTypeName&
const Foam::longReturnTypeName& : Foam::longClassName::longFunctionName const
Foam::longClassName::longFunctionName const
#+END_EXAMPLE
NOR NOR
#+BEGIN_EXAMPLE :const Foam::longReturnTypeName& Foam::longClassName::longFunctionName
const Foam::longReturnTypeName& Foam::longClassName::longFunctionName :const
const
#+END_EXAMPLE
NOR NOR
#+BEGIN_EXAMPLE :const Foam::longReturnTypeName& Foam::longClassName::
const Foam::longReturnTypeName& Foam::longClassName:: :longFunctionName const
longFunctionName const
#+END_EXAMPLE
+ if it needs to be split again, split at the function name (leaving
behind the preceding scoping "::"s), and again, left align, i.e.
+ if need to split again, split at the function name (leaving behind the For example,
preceding scoping "::"s), and again, left align, i.e.
#+BEGIN_EXAMPLE :const Foam::longReturnTypeName&
const Foam::longReturnTypeName& :Foam::veryveryveryverylongClassName::
Foam::veryveryveryverylongClassName:: :veryveryveryverylongFunctionName const
veryveryveryverylongFunctionName const
#+END_EXAMPLE
+ splitting long lines at an "=" **** Splitting long lines at an "="
Indent after split Indent after split
#+BEGIN_EXAMPLE :variableName =
variableName = : longClassName.longFunctionName(longArgument);
longClassName.longFunctionName(longArgument);
#+END_EXAMPLE
OR (where necessary) OR (where necessary)
#+BEGIN_EXAMPLE :variableName =
variableName = : longClassName.longFunctionName
longClassName.longFunctionName : (
( : longArgument1,
longArgument1, : longArgument2
longArgument2 : );
);
#+END_EXAMPLE
NOT NOT
#+BEGIN_EXAMPLE :variableName =
variableName = :longClassName.longFunctionName(longArgument);
longClassName.longFunctionName(longArgument);
#+END_EXAMPLE
NOR NOR
#+BEGIN_EXAMPLE :variableName = longClassName.longFunctionName
variableName = longClassName.longFunctionName :(
( : longArgument1,
longArgument1, : longArgument2
longArgument2 :);
);
#+END_EXAMPLE
*** Maths and Logic *** Maths and Logic
+ operator spacing + operator spacing
...@@ -318,34 +270,201 @@ ...@@ -318,34 +270,201 @@
with the operator on the lower line. Align operator so that first 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. variable, function or bracket on the next line is 4 spaces indented i.e.
#+BEGIN_EXAMPLE :variableName =
variableName = : a * (a + b)
a * (a + b) : - exp(c/d)
- exp(c/d) : * (k + t);
* (k + t);
#+END_EXAMPLE
This is sometime more legible when surrounded by extra parentheses: This is sometime more legible when surrounded by extra parentheses:
#+BEGIN_EXAMPLE :variableName =
variableName = :(
( : a * (a + b)
a * (a + b) : - exp(c/d)
- exp(c/d) : * (k + t)
* (k + t) :);
);
#+END_EXAMPLE
+ 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 outdent the operator so that the next variable to test is aligned with
the four space indentation, i.e. the four space indentation, i.e.
#+BEGIN_EXAMPLE :if
if :(
( : a == true
a == true : && b == c
&& b == c :)
)
#+END_EXAMPLE ** 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 or a
(alternatively) an '@' prefix.
The '@' prefix form is recommended for most Doxygen specials, since it
has the advantage of standing out. It also happens to be what projects
like gcc and VTK are using.
The '\' prefix form, however, looks a bit better for the '\n' newline
command and when escaping single characters - eg, '\@', '\<', '\>', etc.
Since the filtering removes the leading 4 spaces within the blocks, the
Doxygen commmands 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 myPatchType;
: 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.
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
unknown html type, but it seems to work okay anyhow.
*** 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,
:documented namespace 'Foam::functionEntries' within the
:class 'Foam::functionEntry'
+ If nothing else helps, find some sensible header.
eg,
:namespace 'Foam' is documented in the foamVersion.H file
*** 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
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 (an opinion)
Given the origins of OpenFOAM, the British spellings (eg, neighbour and
not neighbor) are generally favoured. For code sections that interact
with external libraries, it can be useful to adopt American spellings,
especially for names that constitute a significant part of the external
library - eg, 'color' within graphics sub-systems.
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,
:myClass.initialize()
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".
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment