Coding-Guidelines.md

@@ -7,7 +7,7 @@ before we even decided them, but their use is definitely suggested.
 General Rules
 -------------
 
-You can find some good rules to start from at http://pixelscommander.com/wp-content/uploads/2014/12/P10.pdf.
+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:
 
@@ -44,31 +44,27 @@ For codestyle checking we use two main tools:
 
 **Linter**
 
-Esiste un linter che vi dice se il codice scritto contiene alcuni problemi
-comuni.. anche cose nostre personali tipo se è stato scritto "Matteo Piazzolla"
-invece di "matteo michele piazzolla" :P
+In the `scripts` folder you will find a linter which which warn you if the code contains
+some common mistakes (and some more personal stuff, like having Matteo Michele Piazzolla
+instead of Michele Piazzolla).
 
-Il linter si trova in ./scripts/linter.sh e va lanciato usando come working
-directory skyward-boardcore. Praticamente
+You should execute if from the main directory, like this:
 
 ```
 cd skyward-boardcore
 ./scripts/linter.sh
 ```
 
-Cose che controlla:
-- Max 80 colonne
-- Evitare tripli \n\n\n
-- Files senza copyright
-- Tab invece di spazi
+Things that are being checked by the linter:
+- Max 80 columns
+- No triple \n\n\n
+- Files without copyright
+- Tab instead of spaces
 - Matteo Michele Piazzolla
-- Lancia cppcheck e controlla che non dia warning (ora ne da tanti, plz fixate)
-- Non ci siano header files con using namespace.
-
-Diciamo che è un software molto molto semplice, è una collezione di chiamate
-a comandi bash. Quindi puo produrre falsi positivi.
-
+- Executes cppcheck and controls that there are no warnings
+- No `using namespace` in header files (see below)
 
+The software is a really simple collection of scripts, and it can produce false-positives.
 
 **CLang**
 
@@ -95,6 +91,8 @@ mettendola fra
 // clang-format on
 ```
 
+Also, below you will find a description of how source files should be structured.
+
 ## Entrypoints Structure
 
 *TODO FILE NAMING CONVENTIONS*
@@ -144,7 +142,7 @@ using namespace std;
 using namespace miosix;
 ```
 
-⚠️ *WARNING*: Putting this in header files is bad practice and get cause trouble. To know more see <https://stackoverflow.com/questions/4872373/why-is-including-using-namespace-into-a-header-file-a-bad-idea-in-c>
+⚠️ *WARNING*: Putting this in header files is bad practice and cancause trouble. To know more see <https://stackoverflow.com/questions/4872373/why-is-including-using-namespace-into-a-header-file-a-bad-idea-in-c>
 
 
 #### 4) Defines
@@ -164,6 +162,9 @@ Example of what you **DON'T** want to do (real life example):
 ```cpp
 typedef Gpio<GPIOA_BASE, 5> SomePin;  //On a Discovery board, this would rapresent the PA5 pin
 ```
+💡 *Pro Tip*: you can move gpio typedefs, constants defines and other configuration stuff 
+ in an external config.h file (in the same directory) and then `#include` it here.
+This will help someone else to change how you configured your object without touching the code.
 
 #### 6) Global variables
 ```cpp
@@ -214,3 +215,8 @@ void useLongNames(int explicitArg)
 
 TODO:
 - name of objects, folders, ifdef miosix...
+
+What's Next
+-------------
+Check some [Best Practices](../wiki/Best-Practices) or
+ start [Writing a Driver](../wiki/Writing-a-Driver).
\ No newline at end of file