zhyang-dev/openfoam
1
0
Fork 0
mirror of https://develop.openfoam.com/Development/openfoam.git synced 2025-11-28 03:28:01 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

STYLE: use #+BEGIN_EXAMPLE / #+END_EXAMPLE in codingStyleGuide.org

Browse Source 
- seems to work more reliably than the previous indented colons
This commit is contained in:
Mark Olesen
2010-04-13 09:08:43 +02:00
parent 5b8b42f0dc
commit 5636df2b5a
1 changed files with 266 additions and 177 deletions
Download Patch File Download Diff File Expand all files Collapse all files

439
doc/codingStyleGuide.org
View File

@ -18,97 +18,116 @@
made with 'break' or 'continue' as part of a control structure.
+ 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.
:Info<< ...
:os << ...
#+BEGIN_EXAMPLE
Info<< ...
os << ...
#+END_EXAMPLE
so
:WarningIn("className::functionName()")
: << "Warning message"
#+BEGIN_EXAMPLE
WarningIn("className::functionName()")
<< "Warning message"
#+END_EXAMPLE
NOT
:WarningIn("className::functionName()")
:<< "Warning message"
#+BEGIN_EXAMPLE
WarningIn("className::functionName()")
<< "Warning message"
#+END_EXAMPLE
+ no unnecessary class section headers, i.e. remove
:// * * * * * * * * * * * * * Private Member Functions * * * * * * * * * * * //
:
:// Check
:
:// Edit
:
:// Write
#+BEGIN_EXAMPLE
// * * * * * * * * * * * * * Private Member Functions * * * * * * * * * * * //
// Check
// Edit
// Write
#+END_EXAMPLE
if they contain nothing, even if planned for 'future use'
+ class titles are centred
:/*---------------------------------------------------------------------------*\
: Class exampleClass Declaration
:\*---------------------------------------------------------------------------*/
#+BEGIN_EXAMPLE
/*---------------------------------------------------------------------------*\
Class exampleClass Declaration
\*---------------------------------------------------------------------------*/
#+END_EXAMPLE
NOT
:/*---------------------------------------------------------------------------*\
: Class exampleClass Declaration
:\*---------------------------------------------------------------------------*/
#+BEGIN_EXAMPLE
/*---------------------------------------------------------------------------*\
Class exampleClass Declaration
\*---------------------------------------------------------------------------*/
#+END_EXAMPLE
*** 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:
+ If adding a comment to the destructor -
use //- and code as a normal function:
://- Destructor
:~className();
#+BEGIN_EXAMPLE
//- Destructor
~className();
#+END_EXAMPLE
+ 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.
*** The =.C= Files
+ Do not open/close namespaces in a =.C= file
Fully scope the function name, i.e.
+ Fully scope the function name, i.e.
:Foam::returnType Foam::className::functionName()
#+BEGIN_EXAMPLE
Foam::returnType Foam::className::functionName()
#+END_EXAMPLE
NOT
:namespace Foam
:{
: ...
:
: returnType className::functionName()
:
: ...
:}
#+BEGIN_EXAMPLE
namespace Foam
{
...
returnType className::functionName()
...
}
#+END_EXAMPLE
EXCEPTION
When there are multiple levels of namespace, they may be used in the =.C=
file, i.e.
:namespace Foam
:{
:namespace compressible
:{
:namespace RASModels
:{
:
: ...
:
:} // End namespace RASModels
:} // End namespace compressible
:} // End namespace Foam
#+BEGIN_EXAMPLE
namespace Foam
{
namespace compressible
{
namespace RASModels
{
...
} // End namespace RASModels
} // End namespace compressible
} // End namespace Foam
#+END_EXAMPLE
+ Use two empty lines between functions
@ -131,64 +150,95 @@
If a class is virtual - make all derived classes virtual.
*** Conditional Statements
:if (condition)
:{
: code;
:}
#+BEGIN_EXAMPLE
if (condition)
{
code;
}
#+END_EXAMPLE
OR
:if
:(
: long condition
:)
:{
: code;
:}
#+BEGIN_EXAMPLE
if
(
long condition
)
{
code;
}
#+END_EXAMPLE
NOT (no space between "if" and "(")
:if(condition)
:{
: code;
:}
#+BEGIN_EXAMPLE
if(condition)
{
code;
}
#+END_EXAMPLE
*** =for= and =while= Loops
:for (i = 0; i < maxI; i++)
:{
: code;
:}
#+BEGIN_EXAMPLE
for (i = 0; i < maxI; i++)
{
code;
}
#+END_EXAMPLE
OR
:for
:(
: i = 0;
: i < maxI;
: i++
:)
:{
: code;
:}
#+BEGIN_EXAMPLE
for
(
i = 0;
i < maxI;
i++
)
{
code;
}
#+END_EXAMPLE
NOT (no space between "for" and "(")
:for(i = 0; i < maxI; i++)
:{
: code;
:}
#+BEGIN_EXAMPLE
for(i = 0; i < maxI; i++)
{
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= , =forAllIter=, etc. loops
*** =forAll=, =forAllIter=, =forAllConstIter=, etc. loops
like =for= loops, but
:forAll(
#+BEGIN_EXAMPLE
forAll(
#+END_EXAMPLE
NOT
:forAll (
#+BEGIN_EXAMPLE
forAll (
#+END_EXAMPLE
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!:
#+BEGIN_EXAMPLE
forAllIter(HashTable<labelPair, edge, Hash<edge> >, foo, iter)
#+END_EXAMPLE
These convenience macros are also generally avoided in other
container classes and OpenFOAM primitive classes.
*** Splitting Over Multiple Lines
@ -198,64 +248,81 @@
+ do not put "const" onto its own line - use a split to keep it with
the function name and arguments.
so:
so
:const Foam::longReturnTypeName&
:Foam::longClassName::longFunctionName const
#+BEGIN_EXAMPLE
const Foam::longReturnTypeName&
Foam::longClassName::longFunctionName const
#+END_EXAMPLE
NOT
:const Foam::longReturnTypeName&
: Foam::longClassName::longFunctionName const
#+BEGIN_EXAMPLE
const Foam::longReturnTypeName&
Foam::longClassName::longFunctionName const
#+END_EXAMPLE
NOR
:const Foam::longReturnTypeName& Foam::longClassName::longFunctionName
:const
#+BEGIN_EXAMPLE
const Foam::longReturnTypeName& Foam::longClassName::longFunctionName
const
#+END_EXAMPLE
NOR
:const Foam::longReturnTypeName& Foam::longClassName::
:longFunctionName const
#+BEGIN_EXAMPLE
const Foam::longReturnTypeName& Foam::longClassName::
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.
For example,
:const Foam::longReturnTypeName&
:Foam::veryveryveryverylongClassName::
:veryveryveryverylongFunctionName const
#+BEGIN_EXAMPLE
const Foam::longReturnTypeName&
Foam::veryveryveryverylongClassName::
veryveryveryverylongFunctionName const
#+END_EXAMPLE
**** Splitting long lines at an "="
Indent after split
:variableName =
: longClassName.longFunctionName(longArgument);
#+BEGIN_EXAMPLE
variableName =
longClassName.longFunctionName(longArgument);
#+END_EXAMPLE
OR (where necessary)
:variableName =
: longClassName.longFunctionName
: (
: longArgument1,
: longArgument2
: );
#+BEGIN_EXAMPLE
variableName =
longClassName.longFunctionName
(
longArgument1,
longArgument2
);
#+END_EXAMPLE
NOT
:variableName =
:longClassName.longFunctionName(longArgument);
#+BEGIN_EXAMPLE
variableName =
longClassName.longFunctionName(longArgument);
#+END_EXAMPLE
NOR
:variableName = longClassName.longFunctionName
:(
: longArgument1,
: longArgument2
:);
#+BEGIN_EXAMPLE
variableName = longClassName.longFunctionName
(
longArgument1,
longArgument2
);
#+END_EXAMPLE
*** Maths and Logic
+ operator spacing
@ -267,34 +334,41 @@
+ a || b, a && b
+ 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
variable, function or bracket on the next line is 4 spaces indented i.e.
:variableName =
: a * (a + b)
: - exp(c/d)
: * (k + t);
#+BEGIN_EXAMPLE
variableName =
a * (a + b)
- exp(c/d)
* (k + t);
#+END_EXAMPLE
This is sometime more legible when surrounded by extra parentheses:
:variableName =
:(
: a * (a + b)
: - exp(c/d)
: * (k + t)
:);
#+BEGIN_EXAMPLE
variableName =
(
a * (a + b)
- exp(c/d)
* (k + t)
);
#+END_EXAMPLE
+ 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.
:if
:(
: a == true
: && b == c
:)
#+BEGIN_EXAMPLE
if
(
a == true
&& b == c
)
#+END_EXAMPLE
** Documentation
@ -315,14 +389,16 @@
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.
#+BEGIN_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.
#+END_EXAMPLE
+ The class name must be qualified by its namespace, otherwise Doxygen
will think you are documenting some other class.
@ -332,11 +408,13 @@
finding these under-documented classes later.
:Class
: Foam::myUnderDocumentedClass
:
:Description
: Foam::myUnderDocumentedClass
#+BEGIN_EXAMPLE
Class
Foam::myUnderDocumentedClass
Description
Foam::myUnderDocumentedClass
#+END_EXAMPLE
+ Use 'Class' and 'Namespace' tags in the header files.
@ -346,11 +424,13 @@
The Description block then applies to documenting the file itself.
:InClass
: Foam::myClass
:
:Description
: Implements the read and writing of files.
#+BEGIN_EXAMPLE
InClass
Foam::myClass
Description
Implements the read and writing of files.
#+END_EXAMPLE
*** Doxygen Special Commands
@ -368,29 +448,31 @@
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
#+BEGIN_EXAMPLE
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
#+END_EXAMPLE
*** HTML Special Commands
@ -399,28 +481,34 @@
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 bad example.
+ The template with type \<HR\> is a better example.
+ The template with type =\<HR\>= is a better example.
+ The template with type <Type> causes Doxygen to complain about an
+ 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,
+ 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'
#+BEGIN_EXAMPLE
documented namespace 'Foam::functionEntries' within the
class 'Foam::functionEntry'
#+END_EXAMPLE
+ If nothing else helps, find some sensible header.
eg,
:namespace 'Foam' is documented in the foamVersion.H file
#+BEGIN_EXAMPLE
namespace 'Foam' is documented in the foamVersion.H file
#+END_EXAMPLE
*** Documenting Typedefs and classes defined via macros
@ -459,7 +547,9 @@
Press.
Eg,
:myClass.initialize()
#+BEGIN_EXAMPLE
myClass.initialize()
#+END_EXAMPLE
The word "its" (possesive) vs. "it's" (colloquial for "it is" or "it has")
@ -468,4 +558,3 @@
Any remaining "it's" are likely an incorrect spelling of "its".