Coding-Conventions-and-Guidelines.md

@@ -90,22 +90,13 @@ Important rules, and notable differences are summarized here:
    - Everything that should not change should be ```const```
    - Access data members using getters and setters
       - for setters use either by value ```setValue(type value)``` or, if ```type``` is not an integral type by reference ```setValue(const type& value)```
-      - for getters use by value ```type getValue() const {return value_;}```, or by reference ```type& value() {return value_;}``` respectively ```const type& value() const {return value_;}```. Note, use the from ```value()``` ONLY when it returns a reference to a data member, i.e. for function chaining. 
+      - for getters use by value ```type getValue() const {return value_;}```, or by reference ```type& value() {return value_;}``` respectively ```const type& value() const {return value_;}```. Note, use the from ```value()``` only when it returns a reference to a data member, i.e. for function chaining. 
    - For logical states, use ```bool isTrue() const``` or ```bool hasThis() const```. Avoid ```bool isNotNeeded() const``` since it is just ```!isNeeded()```.  
    - Data member declarations follow after method declarations.
    - Classes need to be documented with doxygen commands. 
-   - Follow the ```rule of zero/five```. This concerns any of the following methods handling an object lifecyle:
-      - default constructor: ```X()```
-      - copy constructor: ```X(const X&)```
-      - copy assignment: ```operator=(const X&)```
-      - move constructor: ```X(X&&)```
-      - move assignment: ```operator=(X&&)```
-      - this is special, only if any memory allocation needs to be cleaned up, etc, a destructor ```~X()```
-
-     Either you implement any of them (zero), or all of them (five); and if memory/resources must be released also the destructor.  
-      Instead of implementing, you may use the defaults ``` = default``` or ``` = delete``` keywords to indicate desired behavior. 
 
   These simple rules are summarized in the snippet below:
+
   ```
   // forward declarations
   class Beers;
@@ -177,8 +168,21 @@ Important rules, and notable differences are summarized here:
     Wine wine_;
   };
   ```
-  Reflect about the resources the class is holding and if makes sense to move or copy them. 
-  Implement non-default or long components in the *.inl  
+- Reflect about the resources the class is holding and if makes sense to move or copy them. 
+  Implement non-default or long components in the *.inl.
+- Follow the ```rule of zero/five```. This concerns any of the following methods handling an object lifecyle:
+
+      - default constructor: ```X()```
+      - copy constructor: ```X(const X&)```
+      - assignment operator: ```operator=(const X&)```
+      - move constructor: ```X(X&&)```
+      - move assignment operator: ```operator=(X&&)```
+      - this is special, only if any memory allocation needs to be cleaned up, etc, a destructor ```~X()```
+      
+   Technical references: https://en.cppreference.com/w/cpp/language/rule_of_three
+
+   Either you implement any of them (zero), or all of them (five); and if memory/resources must be released also         the destructor. 
+   Instead of implementing, you may use the defaults ``` = default``` or ``` = delete``` keywords to indicate desired behavior. 
 
 - Each functional group of classes has a unit test ```testThis.cpp```
 - Adhere to C++17 standards. In particular:
@@ -267,8 +271,10 @@ Important rules, and notable differences are summarized here:
 
 ## General Rules
 
-- Warnings have to be fixed, when they appear on the system(s) currently used by the CI, by altering the code unless the warning originates from third-party code and cannot be fixed. In that case, the warning should be locally silenced with appropriate pragmas or by locally turning off warnings for that translation unit. 
-- All unit tests must succeed on the specified systems/configurations on gitlab-ci. If tests fail, code is not merged.  Consider to update, extend the CI systems! 
+- Test your code with ```-pedantic``` compiler flag enabled. 
+- Warnings have to be fixed, when they appear on the system(s) currently used by the CI, by altering the code unless the warning originates from third-party code and cannot be fixed. In such cases, developers of the third-party project should be informed. Should the warning be locally silenced, either using appropriate pragmas or locally turning off warnings for that translation unit, documentation should be added in the entry point triggering the 
+warning using the flag ```FIXME```.
+- All unit tests must succeed on the specified systems/configurations on gitlab-ci. If tests fail, code is not merged.  In certain cases, core developing team will consider to update or extend the CI systems.
    - The unit test code coverage should never decrease due to a new merge request. 
 - Exceptions and error handling
    - On major, but rare, errors or malfunction we throw an exception. This is needed and required for complex physics and shower debugging. 
@@ -278,7 +284,7 @@ Important rules, and notable differences are summarized here:
    - There cannot be any raw pointer in the interface of any class or object
      exposed to outside users, there might be (technical) raw pointers for very special (exceptional) cases
      inside of classes.
-   - If needed, revert to std::unique_ptr, or std::shared_ptr (but sparsely).
+   - Consider using standard library smart pointers (```std::unique_ptr```, ```std::shared_ptr```).
 - When you contribute new code, or extend existing code, at the same time provide unit-tests for all functionality.
 - When you contribute new physics algorithms, in addition you also need to provide a validation module (this is still TBD what exactly this means)