View source for Coding Style

= OTB C++ Code Style =

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

OTB try to follow as much as possible '''ITK instructions''' , See:

http://www.vtk.org/Wiki/ITK/Coding_Style_Guide

== Coding style rules at a glance for new contributors == 

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]
    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 (setters/getters shall be reserved to class options, because of the class
model imposed by ITK)
    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 == 

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:
<pre>
/**
* Description of myElement
*/
int myElement
</pre>

A shorter syntax is possible for variable declaration
<pre>
int myElement /**< description of myElement */
</pre>

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

<pre>
/** Brief description.
 * Detailed description. 
 */
class myClass
</pre>

We enforce the use of short descriptions (AUTOBRIEF + final dot).

h3. Useful keywords

{|class="wikitable" border="1" cellpadding="20" cellspacing="0" 
!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 (Group of OTB modules). 
|-
| \ingroup
| Allow to define the functional group (Group of OTB modules). 
|-
| \pre
| Describe precondition of an entity (design by Contract related tags).
|-
| \post
| Describe postcondition of an entity (design by Contract related tags). 
|-
| \invariant
| Describe invariant of an entity (design by Contract related tags). 
|-
|}


h3. Examples

<pre>
/**
 * 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) {}
</pre>

== C++11 support == 

OTB follow ITK convention to activate optionally some useful c++11 features. Those features are defined as Macro which are activated/deactivated depending on compiler configuration. It allows to maintain compatibility with c++98.

Developers must use the following macros:

* ITK_OVERRIDE: In c++11 the override keyword allows you to explicitly define that a function is intended to override the base-class version.  This makes the code more managable and fixes a set of common hard-to-find bugs.
* ITK_NULLPTR: In c++11 there is an explicit nullptr type that introduces a new keyword to serve as a distinguished null pointer constant: nullptr. It is of type nullptr_t, which is implicitly convertible and comparable to any pointer type or pointer-to-member type. It is not implicitly convertible or comparable to integral types, except for bool.