Coding-Guidelines.md

@@ -7,6 +7,10 @@ You can find some good rules for writing safety-critical code here: <http://pixe
 
 The following rules take inspiration from the JSF - C++ Rules, which you can read here: <http://www.stroustrup.com/JSF-AV-rules.pdf>
 
+## **Style Rules**
+
+Use [clang-format](https://clang.llvm.org/docs/ClangFormat.html). Full Stop. There is an extension for it for nearly every IDE/Text Editor in the world: make it run automatically when saving a file and get the rules from the `.clang-format` file in the top directory.
+
 ## **Critical Rules**
 
 These rules shall be followed every single time.
@@ -21,15 +25,17 @@ Avoid undefined behavior where a derived class is destroyed through a reference
 - **Every header file shall be guarded using defines containing the full project path of the file, or by using #pragma once**
   Avoid conflicts when having files with the same name in multiple directories.
   Example: File `src/shared/sensors/ExampleSensor.h`
+
 ```cpp
 #pragma once
 
 //code goes here
 ```
 
-
 ## **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**
@@ -53,6 +59,7 @@ It's very easy to forget to call an object's init() method, leaving objects in a
 - **Use TRACE() instead of printf()** `printf()` is a very heavy function (surprised?) and it's very unlikely you need it when the rocket is flying. TRACEs are like printfs but they are stripped out when compiling the flight binary.
 
 ## **Commenting rules**
+
 - **Every function shall be documented using a doxygen 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.
@@ -62,6 +69,7 @@ This rule is aimed at improving the readability of the code.
 For a guide on how to use doxygen to document the code, take a look here: https://www.stack.nl/~dimitri/doxygen/manual/docblocks.html
 
 ## **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**
@@ -69,6 +77,7 @@ These rules are mostly aimed at keeping the code readable and consistent.
   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()`
   Exception: Acronyms in function names will be UPPERCASE. Example: `bool selfTestIMU()`
@@ -78,16 +87,19 @@ Exception: As for functions, acronyms in class names will be UPPERCASE. Example:
 - **Constants and enum members will be named using ALL_CAPS_WITH_UNDERSCORES**
   Example 1: `float TEMPERATURE_SAMPLE;`
   Example 2:
+
 ```cpp
 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:
+
 ```cpp
 enum EventIDs {
     EV_ID_1,