|
|
|
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 |
