Coding rules

Here are gathered some good practice for coding.

General rules:

• Add comments to the code.
• A comment is usually a sentence starting with a uppercase letter and a point.
• Always use "const" keywords where needed.
• Promote complete names when possible for the variables, in particular when used in several places in the code (example: fv => localPorosity).
• Variables are named using "camel case" rule (e.g. exampleOfVariableName).
• Avoid as much as possible public variables and functions in class.

Name rules:

• Class names start with an uppercase (e.g. Example)
• Internal variables of a class start with an underscore and a lowercase (e.g. _example)
• Class functions start with a lowercase (e.g. example)
• Access functions "get/set":
  • getRefToExample() : can be used to get the reference / the pointer of a variable in order to modify its value;
  • getConstRefToExample() : idem but in read-only access;
  • getExample : use it when you want to return a ariable value or the pointer towards an object;
  • setExample : set a value that may be not exist or through a more complex function than just an assignment;

Doxygen:

• Installation:

  • download with your package manager "doxygen" and "doxygen-gui" and "graphicviz".
  • Create a folder doxygen in our cm3Libraries folder. Inside cm3Libraries/doxygen, create a folder build to store the config file and for temprorary building datas.
  • Launch the assistant doxygen-wizard using the config file and run doxygen.
  • Enjoy

• Comment usage:

  • "//!" is related to a comment of "level 1" appearing in Doxygen. It corresponds to general comments (related to the interface, the purpose or the goal of the function but not to the practical implementation (otherwise, use "//" instead)).
  • "///" is related to a comment of "level 2" appearing in Doxygen.
  • "//" is related to a practical implementation comment that is not visible inside Doxygen (i.e. giving some practical details of the implementation)
  • "//! \todo bla bla bla bla" is a Doxygen tag for remaining tasks that can be highlight and gathered in a particular section in Doxygen.

• Class and function documentation:

  • You can add to a class/function/member a (brief) description by introducing a doxygen comment of level 1 on the line before the declaration. (You can do it after on the same line using "//!<", which is pratical for enum type for example).
  • For the class description, use:

/* \class MyClass
* detailed description bla bla
* bla bla
* bla bla
*/
class MyClass

• For a member function, you can add a detailed description in addition to a brief one by using level 2 doxygen comment just after the level 1 or inside the function implementation.
• You can group functions or variables together inside a same group by starting with the bookmark "//! @name My group" and closing it with "//! @}"

//! @name My group.
//! Description of my group.

//! Description of function 1.
/// Detailled description (which should go in the implementation for readability).
void function1();

//! @}

• CodeLite is able to indentify doxygen comments and bookmarks and allow to generate automatic doxygen comments.