From 5636df2b5a146b760e642b5f702ac7f1c7b48952 Mon Sep 17 00:00:00 2001 From: Mark Olesen Date: Tue, 13 Apr 2010 09:08:43 +0200 Subject: [PATCH] STYLE: use #+BEGIN_EXAMPLE / #+END_EXAMPLE in codingStyleGuide.org - seems to work more reliably than the previous indented colons --- doc/codingStyleGuide.org | 443 +++++++++++++++++++++++---------------- 1 file changed, 266 insertions(+), 177 deletions(-) diff --git a/doc/codingStyleGuide.org b/doc/codingStyleGuide.org index 1604359edd..abd7bd1a00 100644 --- a/doc/codingStyleGuide.org +++ b/doc/codingStyleGuide.org @@ -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, - so that the =<<= symbols align, i.e. + + =<<= 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. - Avoid cluttering the header file with function bodies. + + 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 >, 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
is a bad example. + + The template with type =
= is a bad example. - + The template with type \ is a better example. + + The template with type =\= is a better example. - + The template with type causes Doxygen to complain about an + + The template with 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". -