Coding-Guidelines.md

+These are some rules and guidelines that we decided to adopt in order to write
+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
+-------------
+
+You can find some good rules to start from at 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.
+
+A typical use of an assertion would be as follows:
+```c
+if (!c_assert(p >= 0) == true) {
+ return ERROR;
+ }
+```
+with the assertion defined as follows:
+```c
+#define c_assert(e) ((e) ? (true) : \
+ tst_debugging(”%s,%d: assertion ’%s’ failed\n”, \
+ __FILE__, __LINE__, #e), false)  
+```
+- 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
+
+Codestyle
+-----------
+
+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
+
+Il linter si trova in ./scripts/linter.sh e va lanciato usando come working
+directory skyward-boardcore. Praticamente
+
+```
+cd skyward-boardcore
+./scripts/linter.sh
+```
+
+Cose che controlla:
+- Max 80 colonne
+- Evitare tripli \n\n\n
+- Files senza copyright
+- Tab invece di spazi
+- 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.
+
+
+
+**CLang**
+
+Se avete un plugin per il vostro ide tanto meglio, altrimenti potete lanciarlo
+da command line con
+`cat source.cpp | clang-format > source_figo.cpp`
+oppure
+`clang-format -i source.cpp`
+oppure 
+`find src/ -iname "*.cpp" -exec clang-format -i "{}" \;`
+(ocio a tenere 'src/' se no reindenta tutto miosix XD)
+
+clang-format cerca un file chiamato '.clang-format' nella cartella attuale
+o va a guardare tutte tutte le cartelle sopra. Se non lo trova, usa una config
+di default che non mi piace (lo vedert subito perche usa 2 spazi e parentesi
+in linea).
+
+Ho visto che ogni tanto (non capisco il criterio) decide di indentare male
+le enum belle allineate. Potete evitare che tocchi qualche zona di codice
+mettendola fra
+```
+// clang-format off
+...codice da non toccare
+// clang-format on
+```
+
+## Entrypoints Structure
+
+*TODO FILE NAMING CONVENTIONS*
+
+*TODO COMMENT WITH \arg \returns ?*
+
+#### 1) Copyrigth
+
+You will find different Licence policies along the code: while Miosix's code was released unde the GPL license,
+most of Boardcore has MIT License.
+
+Anyway you want to licence your code, you should indeed put a copyright statement as a first thing in every file.
+```Cpp
+/* Copyright (c) 2015-2016 Skyward Experimental Rocketry
+ * Authors: ...
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+```
+#### 2) Includes
+```cpp
+#include <Common.h>
+#include "Miosix.h"
+//...
+```
+💡 *Pro Tip*:  In Common.h you will find many frequently used headers. Check it!
+
+#### 3) Namespace 
+```cpp
+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>
+
+
+#### 4) Defines
+```cpp
+#define DEBUG
+```
+⚠️ *WARNING*: DON'T abuse defines: they're difficult to read (and can create side effects).
+
+Example of what you **DON'T** want to do (real life example):
+```cpp
+#define SENSOR(NAME, CSPORT, CSPIN)                     \
+    typedef Gpio<GPIO##CSPORT##_BASE, CSPIN> CS_##NAME; \
+    typedef ProtocolSPI<busSPI1, CS_##NAME> spi##NAME
+```
+
+#### 5) Typedefs and  structs
+```cpp
+typedef Gpio<GPIOA_BASE, 5> SomePin;  //On a Discovery board, this would rapresent the PA5 pin
+```
+
+#### 6) Global variables
+```cpp
+int _globalInt;
+```
+
+#### 7) Functions prototypes
+```cpp
+void useLongNames(int explicitArg);
+```
+#### 8) Main
+
+```cpp
+/*
+Put a comment here that explains well how to setup/use the file.
+*/
+int main()
+{
+      //Local variables declaration (all at the start of the function)
+      int localInt;
+
+      //DO STUFF
+      
+}
+
+```
+
+#### 9) Functions bodies
+
+```cpp
+/*
+Put a comment before every function, telling what args they want and what they do.
+*/
+void useLongNames(int explicitArg)
+{
+//BODY of function
+}
+```
+
+## Header Files Structure
+```cpp
+/*LICENSE*/
+#ifndef YOURHEADER_H
+#define YOURHEADER_H
+//Define stuff
+#endif
+```
+
+TODO:
+- name of objects, folders, ifdef miosix...
\ No newline at end of file