Coding-Guidelines.md

@@ -4,25 +4,87 @@ more readable and safe code.
 Following these rules is not *absolutely* necessary, and much of the existing code was written
 before we even decided them, but their use is definitely suggested.
 
-General Rules
+# **Coding Rules**
 --------------
 
 You can find some good rules for writing safety-critical code here: <http://pixelscommander.com/wp-content/uploads/2014/12/P10.pdf>.
 
-Here are some of them:
-
-- Do not use direct or indirect recursion
-- Do not use dynamic memory allocation (`malloc` or `new`) after initialization
-- No function should be longer than about 60 lines
-- The assertion density of the code should average to a minimum of two
-assertions per function.[see [below](#Assertions)]
-- Data objects must be declared at the smallest possible level of scope
-- The return value of non-void functions must be checked by each calling
-function, and the validity of parameters must be checked inside each function
--  The use of the preprocessor must be limited to the inclusion of header files and
-simple macro definitions
-- The use of pointers should be restricted. Specifically, no more than one level of
-dereferencing is allowed
+The following rules take inspiration from the JSF - C++ Rules, which you can read here: <http://www.stroustrup.com/JSF-AV-rules.pdf>
+
+## **Critical Rules**  
+  
+These rules shall be followed every single time.
+An exception to these rules can be made only after extensive consultation with the majority of the software team. Every deviation from this rules shall be documented in place with the reasoning behind the decision.
+
+- **Do not use dynamic memory allocation (`malloc` or `new`) after initialization**  
+The use of dynamic allocation can lead to heap fragmentation and out-of-memory errors after the startup of the rocket (eg. In flight)
+- **Do not use direct or indirect recursion**  
+Recursive code is hard to read and debug, and can easy lead to stack overflow errors.
+- **Every class with a virtual function shall define a virtual destructor**  
+Avoid undefined behavior where a derived class is destroyed through a reference to the base class, possibly leaking resources.
+
+## **General rules**  
+These are not critical rules, but you should follow them in most cases.  
+- **Check the validity of the input arguments for every function**  
+Avoid errors caused by out-of-domain or otherwise wrong input arguments.
+- **Avoid throwing exceptions**  
+Exceptions can cause the program to crash if not handled correctly.
+- **Every nonlocal name, except main(), should be placed in some namespace**  
+- **Data objects must be declared at the smallest possible level of scope**
+- **Prefer inline function over macros. Macros should be avoided or kept as simple as possible**  
+While sometimes useful, macros kill the readability of the code. Avoid them when you can, and if you use them, keep them simple and comment them appropriately.
+- **Constant values should be not be defined using the #define directive**  
+Prefer `static const` instead, to improve readability and avoid type ambiguities.
+- **Variables should not be introduced until they can be initialized with meaningful values**  
+Avoid errors where someone tries to use an uninitialized variable.
+- **Avoid pointers and prefer references, when possible**
+- **Prefer enum class over plain, c-style enum**  
+Enum classes restrict the scope of their members and are strongly-typed.
+- **The return value of non-void functions must be checked by each calling**  
+This is done to check if the function had an error.
+- **Use C++ style cast (static_cast, dynamic_cast…) instead of their C counterparts**
+
+## **Commenting rules**
+- **Every function shall be preceded by a doxygen-style comment describing the purpose of the function, its parameters and the return value.**
+- **Write a comment defining pre and post-conditions for most methods.**  
+This rule is aimed at improving the readability of the code. 
+- **Write a comment describing every variable when its meaning is not trivial**
+- **Write a comment describing the purpose of each class, struct and enum**
+
+## **Best practices**
+These rules are mostly aimed at keeping the code readable and consistent.
+
+- **Functions generally should return an integer value which tells the caller if there were problems**
+- **No function should be longer than about 80 lines**
+Split functions in multiple ones to improve readability of the code
+
+## **Naming conventions**
+- **Function will be named using camelCaseNotation, starting with a lower case letter**  
+Example: `float readTemperatureSample()`
+- **Classes, structs and enums will be named using CamelCaseNotation**  
+Example: `class TemperatureSensor{};`
+- **Constants and enum members will be named using ALL_CAPS_WITH_UNDERSCORES**  
+Example 1: `float TEMPERATURE_SAMPLE;`  
+Example 2:  
+```
+enum class ExampleEnum {  
+    EXAMPLE_MEMBER_1,  
+    EXAMPLE_MEMBER_2  
+}
+```
+- **Local and member variables will be named all_lowercase_with_underscores**  
+Example 1: `float pressure_sample;`
+- **Names of members of c-style enums shall begin with a identifier of the enum, to avoid ambiguities, since they are not scoped**  
+Example 2:  
+```
+enum EventIDs {  
+    EV_ID_1,
+    EV_ID_2
+}
+```
+
+
+
 
 Best Practices
 -------------------