1.1.0
CCC
  
Public Member Functions | Static Public Member Functions | List of all members
Style Class Reference

The Style class contains all the recommended styles considerations. It has no special functionalities.
This is only a template class that developers can mimic. More...

#include <Style.hpp>

Public Member Functions

 Style ()
 
 Style (const Style &r)
 
Style & operator= (const Style &r)
 
virtual ~Style ()
 
int DocumentedStandard (int myArg) const
 
int DocumentedWithFormula (int myArg) const
 
int UnusedArgument (int a)
 
double getArgDouble () const
 
int getArgInt () const
 
const VectorDouble & getArgVectorDouble () const
 
const VectorInt & getArgVectorInt () const
 
void setArgDouble (double argDouble)
 
void setArgInt (int argInt)
 
void setArgVectorDouble (const VectorDouble &argVectorDouble)
 
void setArgVectorInt (const VectorInt &argVectorInt)
 

Static Public Member Functions

static void myFunction (int myArgInt, double myArgDoubleDef=2.)
 

Detailed Description

The Style class contains all the recommended styles considerations. It has no special functionalities.
This is only a template class that developers can mimic.

This class includes coding rules and doxygen documentation examples.

Since doxygen 1.8.0, Markdown support is available in doxygen comments (see here).
Look at gstlearn READMEs for a quick overview of Markdown syntax.

Main class features

This class demonstrates:

  • How to use doxygen for documenting the class:
    • this global class description
    • the private member attributes documentation
    • all methods and arguments documentation (at least public ones)
  • Some mandatory coding rules (see below):
    • constructors
    • pro active usage of const
    • error handling with exceptions,
    • etc...
  • How to use some gstlearn global features such has:
    • Enumerations (see AEnum) - TODO
    • DECLARE_UNUSED macro (need including geoslib_define.h)
    • ...to be expanded
  • Some coding constraints due to the [customized] SWIG for R version:
    • limit the use of function overriding
    • do not use namespace or static variables in default argument values
    • do not comment the argument name when it is unused (use DECLARE_UNUSED)
    • do not use following argument names: 'in', '_*'
    • always inherit from pure virtual classes in last position (ex: ICloneable)

C++ naming convention

Here are some rules about naming C++ types, functions, variables and symbols:

  • Only usual abbreviations are accepted (ie: min, max, idx, temp, ...)
  • Constants (macro): all in capitals with underscore (MAX_LENGTH)
  • Enums: idem
  • Class or structure names: upper camel case (ie: SparseMatrix, Database)
  • Aliases (typedef): idem
  • Class' methods: lower camel case (ie: loadData, getArmonicMean, isEmpty)
  • Class' attributes (variables): idem
  • Anything which is private or protected in a class starts with underscore (ie: myMember)
  • Local variables: lower case separated by underscore (i.e.: temp_value, color_idx)
  • Methods naming; method _func() is internal to the class (private or protected) method func() is not exported via SWIG
  • Use of "InPlace" suffix: It is used in methods that modify either a member of this class or a returned argument. Important remark. The member or agument must have been correctly dimensioned beforehand; no test will be performed (in order to speed up the processing).

C++ coding rules

Here are some coding rules (good practices) for C++ developers:

  • Do not use goto
  • Use break only in switch cases
  • Limit the number of global variables
  • Use const every where
  • Do not use old C-style (use C++ STL)
  • Do not use using namespace
  • Make the includes list as small as possible in C++ header (use forward declaration)
  • Expose only what is necessary (all is private by default)

More good practices available here

Class' constructors/destructors

Here are some rules regarding constructors and destructors:

  • Always add a default constructor (no arguments or arguments with default values)
  • Always add a copy constructor (with some exceptions - see Calc* classes)
  • Always add an assignment operator (with some exceptions - see Calc* classes)
  • Always add a virtual destructor

Documenting Methods

Main principles for documenting class methods are the following:

  • Add one-line comment before each public prototype in the C++ header
  • Add a doxygen section above each method definition in the C++ body
  • All this except for trivial methods*, constructors and destructors
  • Define pointer for ENUM. Example to point to EMorpho Enum: EMorpho

Constructor & Destructor Documentation

Style::Style ( )

Default constructor

Always use the initialization list to set the default value of each class member. Put attributes in the same order than their declaration in the C++ header.

Style::Style ( const Style &  r)

Copy constructor

Always use the initialization list to set the value of each class member. Put attributes in the same order than their declaration in the C++ header.

Style::~Style ( )
virtual

Destructor

Always free pointers and clear the lists of the class

Member Function Documentation

int Style::DocumentedStandard ( int  myArg) const

A method with standard argument documentation

Parameters
[in]myArgHere should be placed the description of this argument
Returns
Description of the returned value
int Style::DocumentedWithFormula ( int  myArg) const

Documentation with Latex formula

The distance between $ p1=(x_1,y_1) $ and $ p2=(x_2,y_2) $ is $\sqrt{(x_2-x_1)^2+(y_2-y_1)^2}$ (this formula may need to do this: https://github.com/doxygen/doxygen/issues/7484#issuecomment-572503569)

See also
SpaceRN::getDistance
Parameters
[in]myArgHere should be placed the description of this argument
Returns
The value of the argument + 1
void Style::myFunction ( int  myArgInt,
double  myArgDoubleDef = 2. 
)
static

Description of a static function

Parameters
[in]myArgIntInteger argument
[in]myArgDoubleDefDouble argument
Style & Style::operator= ( const Style &  r)

Assignment operator

Always protect from self copy if the if statement

int Style::UnusedArgument ( int  a)

A function where the argument is not used (could be the case in abstract methods)

Parameters
[in]aInput argument not used (but documented)
Returns
Error returned code
The documentation for this class was generated from the following files: