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.
This commit is contained in:
Mark Olesen
parent
fa93ce8cd7
commit
6f14809234
@ -109,7 +109,7 @@ eg,
|
||||
|
|
||||
| Within the implementation, a loop over all patches is done:
|
||||
| @code
|
||||
| forAll (patches, patchI)
|
||||
| forAll(patches, patchI)
|
||||
| {
|
||||
| ... // some operation
|
||||
| }
|
||||
@ -222,4 +222,4 @@ The doc/Doxygen/tools directory contains miscellaneous scripts for finding
|
||||
and possibly repairing documentation issues.
|
||||
|
||||
|
||||
Updated: 2008-03-17
|
||||
Updated: 2009-11-27
|
||||
|
||||
@ -17,292 +17,244 @@
|
||||
+ Avoid trailing whitespace.
|
||||
|
||||
+ stream output
|
||||
<< is always four characters after the start of the stream,
|
||||
so that the << symbols align, i.e.
|
||||
=<<= is always four characters after the start of the stream,
|
||||
so that the =<<= symbols align, i.e.
|
||||
|
||||
#+BEGIN_EXAMPLE
|
||||
Info<< ...
|
||||
os << ...
|
||||
#+END_EXAMPLE
|
||||
:Info<< ...
|
||||
:os << ...
|
||||
|
||||
so
|
||||
|
||||
#+BEGIN_EXAMPLE
|
||||
WarningIn("className::functionName()")
|
||||
<< "Warning message"
|
||||
#+END_EXAMPLE
|
||||
:WarningIn("className::functionName()")
|
||||
: << "Warning message"
|
||||
|
||||
NOT
|
||||
|
||||
#+BEGIN_EXAMPLE
|
||||
WarningIn("className::functionName()")
|
||||
<< "Warning message"
|
||||
#+END_EXAMPLE
|
||||
:WarningIn("className::functionName()")
|
||||
:<< "Warning message"
|
||||
|
||||
|
||||
+ no unnecessary class section headers, i.e. remove
|
||||
|
||||
#+BEGIN_EXAMPLE
|
||||
// * * * * * * * * * * * * * Private Member Functions * * * * * * * * * * * //
|
||||
|
||||
// Check
|
||||
|
||||
// Edit
|
||||
|
||||
// Write
|
||||
#+END_EXAMPLE
|
||||
:// * * * * * * * * * * * * * Private Member Functions * * * * * * * * * * * //
|
||||
:
|
||||
:// Check
|
||||
:
|
||||
:// Edit
|
||||
:
|
||||
:// Write
|
||||
|
||||
if they contain nothing, even if planned for 'future use'
|
||||
|
||||
+ class titles are centred
|
||||
|
||||
#+BEGIN_EXAMPLE
|
||||
/*---------------------------------------------------------------------------*\
|
||||
Class exampleClass Declaration
|
||||
\*---------------------------------------------------------------------------*/
|
||||
#+END_EXAMPLE
|
||||
:/*---------------------------------------------------------------------------*\
|
||||
: Class exampleClass Declaration
|
||||
:\*---------------------------------------------------------------------------*/
|
||||
|
||||
NOT
|
||||
NOT
|
||||
|
||||
#+BEGIN_EXAMPLE
|
||||
/*---------------------------------------------------------------------------*\
|
||||
Class exampleClass Declaration
|
||||
\*---------------------------------------------------------------------------*/
|
||||
#+END_EXAMPLE
|
||||
:/*---------------------------------------------------------------------------*\
|
||||
: Class exampleClass Declaration
|
||||
:\*---------------------------------------------------------------------------*/
|
||||
|
||||
*** .H Files
|
||||
*** The =.H= Files
|
||||
+ 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
|
||||
+ add descriptions to class data and functions
|
||||
+ destructor
|
||||
If adding a comment to the destructor - use //- and code as a normal function:
|
||||
|
||||
#+BEGIN_EXAMPLE
|
||||
//- Destructor
|
||||
~className();
|
||||
#+END_EXAMPLE
|
||||
://- Destructor
|
||||
:~className();
|
||||
|
||||
+ inline functions
|
||||
Use inline functions where appropriate in a separate classNameI.H file.
|
||||
Avoid cluttering the header file with function bodies.
|
||||
|
||||
*** .C Files
|
||||
+ Do not open/close namespaces in a .C file
|
||||
*** The =.C= Files
|
||||
+ Do not open/close namespaces in a =.C= file
|
||||
Fully scope the function name, i.e.
|
||||
|
||||
#+BEGIN_EXAMPLE
|
||||
Foam::returnType Foam::className::functionName()
|
||||
#+END_EXAMPLE
|
||||
:Foam::returnType Foam::className::functionName()
|
||||
|
||||
NOT
|
||||
|
||||
#+BEGIN_EXAMPLE
|
||||
namespace Foam
|
||||
{
|
||||
...
|
||||
|
||||
returnType className::functionName()
|
||||
|
||||
...
|
||||
}
|
||||
#+END_EXAMPLE
|
||||
:namespace Foam
|
||||
:{
|
||||
: ...
|
||||
:
|
||||
: returnType className::functionName()
|
||||
:
|
||||
: ...
|
||||
:}
|
||||
|
||||
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.
|
||||
|
||||
#+BEGIN_EXAMPLE
|
||||
namespace Foam
|
||||
{
|
||||
namespace compressible
|
||||
{
|
||||
namespace RASModels
|
||||
{
|
||||
|
||||
...
|
||||
|
||||
} // End namespace RASModels
|
||||
} // End namespace compressible
|
||||
} // End namespace Foam
|
||||
#+END_EXAMPLE
|
||||
:namespace Foam
|
||||
:{
|
||||
:namespace compressible
|
||||
:{
|
||||
:namespace RASModels
|
||||
:{
|
||||
:
|
||||
: ...
|
||||
:
|
||||
:} // End namespace RASModels
|
||||
:} // End namespace compressible
|
||||
:} // End namespace Foam
|
||||
|
||||
+ Use two empty lines between functions
|
||||
|
||||
*** Coding Practise
|
||||
*** Coding Practice
|
||||
+ passing data as arguments or return
|
||||
Pass bool, label and scalar as copy, anything larger by reference.
|
||||
|
||||
+ const
|
||||
Use everywhere it is applicable.
|
||||
|
||||
+ variable initialisation using "="
|
||||
|
||||
#+BEGIN_EXAMPLE
|
||||
const className& variableName = otherClass.data();
|
||||
#+END_EXAMPLE
|
||||
: const className& variableName = otherClass.data();
|
||||
|
||||
NOT
|
||||
|
||||
#+BEGIN_EXAMPLE
|
||||
const className& variableName(otherClass.data());
|
||||
#+END_EXAMPLE
|
||||
: const className& variableName(otherClass.data());
|
||||
|
||||
+ virtual functions
|
||||
If a class is virtual - make all derived classes virtual.
|
||||
|
||||
*** Conditional Statements
|
||||
#+BEGIN_EXAMPLE
|
||||
if (condition)
|
||||
{
|
||||
code;
|
||||
}
|
||||
#+END_EXAMPLE
|
||||
:if (condition)
|
||||
:{
|
||||
: code;
|
||||
:}
|
||||
|
||||
OR
|
||||
|
||||
#+BEGIN_EXAMPLE
|
||||
if
|
||||
(
|
||||
long condition
|
||||
)
|
||||
{
|
||||
code;
|
||||
}
|
||||
#+END_EXAMPLE
|
||||
:if
|
||||
:(
|
||||
: long condition
|
||||
:)
|
||||
:{
|
||||
: code;
|
||||
:}
|
||||
|
||||
NOT (no space between "if" and "(")
|
||||
|
||||
#+BEGIN_EXAMPLE
|
||||
if(condition)
|
||||
{
|
||||
code;
|
||||
}
|
||||
#+END_EXAMPLE
|
||||
:if(condition)
|
||||
:{
|
||||
: code;
|
||||
:}
|
||||
|
||||
*** `for' Loops
|
||||
#+BEGIN_EXAMPLE
|
||||
for (i = 0; i < maxI; i++)
|
||||
{
|
||||
code;
|
||||
}
|
||||
#+END_EXAMPLE
|
||||
*** =for= Loops
|
||||
:for (i = 0; i < maxI; i++)
|
||||
:{
|
||||
: code;
|
||||
:}
|
||||
|
||||
OR
|
||||
|
||||
#+BEGIN_EXAMPLE
|
||||
for
|
||||
(
|
||||
i = 0;
|
||||
i < maxI;
|
||||
i++
|
||||
)
|
||||
{
|
||||
code;
|
||||
}
|
||||
#+END_EXAMPLE
|
||||
:for
|
||||
:(
|
||||
: i = 0;
|
||||
: i < maxI;
|
||||
: i++
|
||||
:)
|
||||
:{
|
||||
: code;
|
||||
:}
|
||||
|
||||
NOT (no space between "for" and "(")
|
||||
|
||||
#+BEGIN_EXAMPLE
|
||||
for(i = 0; i < maxI; i++)
|
||||
{
|
||||
code;
|
||||
}
|
||||
#+END_EXAMPLE
|
||||
:for(i = 0; i < maxI; i++)
|
||||
:{
|
||||
: code;
|
||||
:}
|
||||
|
||||
*** `forAll' loops
|
||||
like for loops, but
|
||||
Note that when indexing through iterators, it is often slightly more
|
||||
efficient to use the pre-increment form. Eg, =++iter= instead of =iter++=
|
||||
|
||||
#+BEGIN_EXAMPLE
|
||||
forAll(
|
||||
#+END_EXAMPLE
|
||||
*** =forAll= loops
|
||||
like =for= loops, but
|
||||
|
||||
:forAll(
|
||||
|
||||
NOT
|
||||
|
||||
#+BEGIN_EXAMPLE
|
||||
forAll (
|
||||
#+END_EXAMPLE
|
||||
:forAll (
|
||||
|
||||
*** 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
|
||||
|
||||
+ do not put "const" onto its own line - use a split to keep it with the
|
||||
function name and arguments.
|
||||
+ do not put "const" onto its own line - use a split to keep it with
|
||||
the function name and arguments.
|
||||
|
||||
so:
|
||||
|
||||
#+BEGIN_EXAMPLE
|
||||
const Foam::longReturnTypeName&
|
||||
Foam::longClassName::longFunctionName const
|
||||
#+END_EXAMPLE
|
||||
:const Foam::longReturnTypeName&
|
||||
:Foam::longClassName::longFunctionName const
|
||||
|
||||
NOT
|
||||
|
||||
#+BEGIN_EXAMPLE
|
||||
const Foam::longReturnTypeName&
|
||||
Foam::longClassName::longFunctionName const
|
||||
#+END_EXAMPLE
|
||||
:const Foam::longReturnTypeName&
|
||||
: Foam::longClassName::longFunctionName const
|
||||
|
||||
NOR
|
||||
|
||||
#+BEGIN_EXAMPLE
|
||||
const Foam::longReturnTypeName& Foam::longClassName::longFunctionName
|
||||
const
|
||||
#+END_EXAMPLE
|
||||
:const Foam::longReturnTypeName& Foam::longClassName::longFunctionName
|
||||
:const
|
||||
|
||||
NOR
|
||||
|
||||
#+BEGIN_EXAMPLE
|
||||
const Foam::longReturnTypeName& Foam::longClassName::
|
||||
longFunctionName const
|
||||
#+END_EXAMPLE
|
||||
:const Foam::longReturnTypeName& Foam::longClassName::
|
||||
:longFunctionName const
|
||||
|
||||
|
||||
+ if need to split again, split at the function name (leaving behind the
|
||||
preceding scoping "::"s), and again, left align, i.e.
|
||||
+ 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_EXAMPLE
|
||||
const Foam::longReturnTypeName&
|
||||
Foam::veryveryveryverylongClassName::
|
||||
veryveryveryverylongFunctionName const
|
||||
#+END_EXAMPLE
|
||||
For example,
|
||||
|
||||
+ splitting long lines at an "="
|
||||
:const Foam::longReturnTypeName&
|
||||
:Foam::veryveryveryverylongClassName::
|
||||
:veryveryveryverylongFunctionName const
|
||||
|
||||
**** Splitting long lines at an "="
|
||||
|
||||
Indent after split
|
||||
|
||||
#+BEGIN_EXAMPLE
|
||||
variableName =
|
||||
longClassName.longFunctionName(longArgument);
|
||||
#+END_EXAMPLE
|
||||
:variableName =
|
||||
: longClassName.longFunctionName(longArgument);
|
||||
|
||||
OR (where necessary)
|
||||
|
||||
#+BEGIN_EXAMPLE
|
||||
variableName =
|
||||
longClassName.longFunctionName
|
||||
(
|
||||
longArgument1,
|
||||
longArgument2
|
||||
);
|
||||
#+END_EXAMPLE
|
||||
:variableName =
|
||||
: longClassName.longFunctionName
|
||||
: (
|
||||
: longArgument1,
|
||||
: longArgument2
|
||||
: );
|
||||
|
||||
NOT
|
||||
|
||||
#+BEGIN_EXAMPLE
|
||||
variableName =
|
||||
longClassName.longFunctionName(longArgument);
|
||||
#+END_EXAMPLE
|
||||
:variableName =
|
||||
:longClassName.longFunctionName(longArgument);
|
||||
|
||||
NOR
|
||||
|
||||
#+BEGIN_EXAMPLE
|
||||
variableName = longClassName.longFunctionName
|
||||
(
|
||||
longArgument1,
|
||||
longArgument2
|
||||
);
|
||||
#+END_EXAMPLE
|
||||
:variableName = longClassName.longFunctionName
|
||||
:(
|
||||
: longArgument1,
|
||||
: longArgument2
|
||||
:);
|
||||
|
||||
*** Maths and Logic
|
||||
+ operator spacing
|
||||
@ -318,34 +270,201 @@
|
||||
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.
|
||||
|
||||
#+BEGIN_EXAMPLE
|
||||
variableName =
|
||||
a * (a + b)
|
||||
- exp(c/d)
|
||||
* (k + t);
|
||||
#+END_EXAMPLE
|
||||
:variableName =
|
||||
: a * (a + b)
|
||||
: - exp(c/d)
|
||||
: * (k + t);
|
||||
|
||||
This is sometime more legible when surrounded by extra parentheses:
|
||||
|
||||
#+BEGIN_EXAMPLE
|
||||
variableName =
|
||||
(
|
||||
a * (a + b)
|
||||
- exp(c/d)
|
||||
* (k + t)
|
||||
);
|
||||
#+END_EXAMPLE
|
||||
:variableName =
|
||||
:(
|
||||
: a * (a + b)
|
||||
: - exp(c/d)
|
||||
: * (k + t)
|
||||
:);
|
||||
|
||||
+ 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.
|
||||
|
||||
#+BEGIN_EXAMPLE
|
||||
if
|
||||
(
|
||||
a == true
|
||||
&& b == c
|
||||
)
|
||||
#+END_EXAMPLE
|
||||
:if
|
||||
:(
|
||||
: a == true
|
||||
: && b == c
|
||||
:)
|
||||
|
||||
** 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".
|
||||
|
||||
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user