Coding-rules.md

@@ -2,6 +2,7 @@ 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).
@@ -35,7 +36,7 @@ Here are gathered some good practice for coding.
    * For the class description, use:
 ```
 /* \class MyClass
-* detailed description
+* detailed description bla bla
 * bla bla
 * bla bla
 */
@@ -43,6 +44,16 @@ 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.