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:

/**
* Description of myElement
*/
int myElement

A shorter syntax is possible for variable declaration

int myElement /**< description of myElement */

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):

/** Brief description.
 * Detailed description. 
 */
class myClass

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

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 (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

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

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.