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>

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
• When functions should not be used anymore by developpers, use GSTLEARN_DEPRECATED in body of function definition (see Db::getActiveSampleNumber())
• When functions are kept in order to be refactored later, put TODO FUTURE_REFACTOR as a comment
• 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 visibility; Method _func() is internal to the class (private or protected) Method func() is not exported via SWIG (using ifndef 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

Important note: All C++ coding rules are configured in the .clang-format file. located in the root folder. Developers can use the "Clang format" VS code extension to benefit from the automatic formating feature

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

Public Member Functions
	Style ()
	Style (const Style &r)
Style &	operator= (const Style &r)
virtual	~Style ()
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 int	documentedStandard (int myArg)
static int	documentedWithFormula (int myArg)
static int	unusedArgument (int a)
static void	myFunction (int myArgInt, double myArgDoubleDef=2.)

Constructor & Destructor Documentation

Style() [1/2]

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() [2/2]

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::~Style ( )

virtual

Destructor

Always free pointers and clear the lists members of the class

Member Function Documentation

documentedStandard()

int Style::documentedStandard ( int  myArg )

static

A method with standard argument documentation

Parameters

[in]

myArg

Here should be placed the description of this argument

Returns

Description of the returned value

documentedWithFormula()

int Style::documentedWithFormula ( int  myArg )

static

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]

myArg

Here should be placed the description of this argument

Returns

The value of the argument + 1

myFunction()

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

static

Description of a static function

Parameters

[in]	myArgInt	Integer argument
[in]	myArgDoubleDef	Double argument

operator=()

Style & Style::operator=

(

const Style &

r

)

Assignment operator

Always protect from self copy with the if statement

unusedArgument()

int Style::unusedArgument ( int  a )

static

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

Parameters

[in]

a

Input argument not used (but documented)

Returns

Error returned code

---

The documentation for this class was generated from the following files:

• include/API/Style.hpp
• src/API/Style.cpp