Coding Style

From OTBWiki
Revision as of 14:54, 13 January 2016 by Manuel.grizonnet (Talk | contribs) (Created page with "= C++ Code Style = The document describes OTB coding conventions. Developers should follow these conventions when submitting contributions. OTB follows ITK instructions loca...")

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

C++ Code Style

The document describes OTB coding conventions. Developers should follow these conventions when submitting contributions.

OTB follows ITK instructions located [[1]]

Coding style rules

Please try your best to enforce Orfeo ToolBox coding style and architecture. The OTB coding style can be summarized with a set of rules :

   LEN: Line Length = 120 max chars (ideally 80 chars)
   IVR: ivars should match regular expression: m_[A-Z][A-Za-z0-9]*
   IVA: ivars should be aligned with previous ivars
   SEM: Semicolons = 0 max spaces
   DCL: Declaration order should match Public/Protected/Private
   EOF: The file should have only one new line
   TAB: The file should not have any tabs
   ESP: Spaces at the end of line = 3 max spaces (but 0 is still better)
   HRD: The header should respect the template
   DEF: #ifndef/#define should match __[NameOfClass]_[Extension] (starting with "__" triggers -Wreserved-id-macro warning in clang.)
   TDR: Typedefs should match regular expression: [A-Z]
   TDA: Typedefs should be aligned
   NMC: The name of the class should match otb[NameOfClass]
   WCM: The comments are misspelled
   MCM: The class declaration should come after a comment bloc starting with \class (allowing empty line)
   EML: Empty lines = 2 max lines
   TPL: Template should match the regex: [TNV]
   OPS: Number of spaces for the operators shoud be: before=1, after=1 

In addition, don't forget to document your code, use explicit variable names and be consistent in your naming choices.

On the architecture side, try to be consistent with the way existing OTB filters are developed :

   Make use of ITK SmartPointers when needed (beware of memory management issues)
   Prefer private attributes, with public getter/setter
   Use the 'otb' namespace
   Make use of existing classes in OTB or ITK when possible (don't re-invent the wheel)
   Take some time to understand how an OTB pipeline works (check the sources of classes itk::DataObject and itk::ProcessObject)

There are also a lot of code examples that show how OTB classes are used.

Doxygen

best practices guide draft:

OTB and Doxygen Best Practices

Doxygen is an open-source, powerful system for automatically generating documentation from source code. To use Doxygen effectively, the developer must insert comments, delimited in a special way, that Doxygen extracts to produce the documentation. While there are a large number of options to Doxygen, developers at a minimum should insert the following Doxygen commands.

Doxygen website: http://www.stack.nl/dimitri/doxygen/index.html Doxygen manual: http://www.stack.nl/~dimitri/doxygen/manual/index.html

h3. Documentation rules

To describe an element you should use the following syntax before the element: {noformat} /**

  • Description of myElement
  • /

int myElement {noformat}

A shorter syntax is possible for variable declaration {noformat} int myElement /**< description of myElement */ {noformat}

We don't need to use the \class or the \brief keywords, the following syntax allow to describe a class (with AUTOBRIEF option):

{noformat} /** Brief description.

* Detailed description. 
*/

class myClass {noformat}

h3. Useful keywords

||Tags||Description|| |\see|Allow to add a link to an other code element or to add a URL| |\param|Describe the parameters of a function and their role in or/and out (see following example).| |\since|Allow to define the first version where the element is available.| |\throw|Allow to describe the exceptions return by a function.| |\return|Allow to describe the return data but no need to describe its type (see examples). | |\tparam|Allow to describe the template type (see examples). | |\ingroup| Allow to define the functional group (linkl to modularity). |

h3. Example

{noformat} /**

* Brief description. 
* 
* Detailed description
* \since version_number
* \see Url of an example of the name the related class(es).
* \ingroup myGroup
*/

template <class TMyType> class myClass {

template <class TMyType> /**

* Brief Description.
* \tparam TypeName Descrition of the type
* \param[in] InputParameterName Description of the input parameter
* \param[out] OutputParameterName Description of the output parameter
* \return Description of the return object (if return void, the keyword is not necessary)  
* \throw Description of the exception or None     
*
* Detailed description. 
*/
void myFunction(int InputParameterName, int OutputParameterName) {}

{noformat}