Convenzioni per la scrittura di codice C nei sistemi embedded

1) Leggibilità del codice
  1a) Utilizzo attento dei nomi
  1b) Indentazione del codice
  1c) Documentazione del codice
2) Layering
3) Evitare l'utilizzo dei "magic numbers" all'interno del codice

- http://users.ece.cmu.edu/~eno/coding/CCodingStandard.html
- http://users.ece.utexas.edu/~valvano/EE345L/Labs/Fall2011/style.pdf

Prima di imparare a scrivere programmi perfettamente funzionanti e performanti dovete imparare a scrivere codice chiaro e facilmente comprensibile, per voi e per le persone appartenenti al vostro gruppo di lavoro.
Diventa quindi importante rispettare, durante la scrittura del codice, stili e regole condivise.

I COMMENTI
I commenti presenti nei programmi saranno su tre livelli:
1. intestazione del modulo:

//==========================================================================================
//
// Project: <nome del progetto>
// Date: <data>
// Author:<autore>
//
//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
//
//  <inserire una breve descrizione del progetto>
//  <specifiche del progetto>
//  <specifiche del collaudo>
//
// Ver Date Comment
//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
// 1.0.0 14.11.15 Versione iniziale
// <Descrivere per ogni revisione o cambio di versione le modifiche apportate>
//
//==========================================================================================

2. intestazione delle routine:
//------------------------------------------------------------------------------------------
//
//  <inserire una breve descrizione della routine>
//
// INPUT:           <elenco dei parametri in ingresso alla funzione>
// OUTPUT:          <valori restituiti>
//
//  04.02.14    1.0     Versione iniziale
//  <data> <Revision History> <Descrivere per ogni revisione o cambio di versione le modifiche apportate>
//

3. gruppi o singole istruzioni: i commenti che precedono il gruppi di istruzioni seguono l'indentazione del codice; per  le singole istruzioni il commento va messo preferibilmente a destra dell'istruzione stessa. Scriver i commenti prima del codice, scrivere cosa avete intenziore di fare seguendo quanto già scritto nei diagrammi
// Defines for I2C
// GPIO register offsets from BCM2835_BSC*_BASE.
// Offsets into the BSC Peripheral block in bytes per 3.1 BSC Register Map
#define BCM2835_BSC_C        0x0000 // BSC Master Control
#define BCM2835_BSC_S        0x0004 // BSC Master Status
#define BCM2835_BSC_DLEN     0x0008 // BSC Master Data Length
#define BCM2835_BSC_A        0x000c // BSC Master Slave Address

NOMI
- Per i nomi usare la notazione CamelCase
- le variabili e le funzioni con visibilità globale (su altri moduli) Iniziano con la maiuscola
- i nomi delle costanti sono con tutti i caratteri maiuscoli e separati dal carattere underscore (_)

SEZIONI DEL FILE
rendere evidenti tramite dei commenti separatori le varie sezioni del file
Nei moduli .c
//------------------------------------------------------------------------------------------
//=== Includes =============================================================================
//------------------------------------------------------------------------------------------
//=== Local constants  =====================================================================
//=== Local function prototypes ============================================================
//=== Local variables ======================================================================
//=== Local Functions ======================================================================
//=== Global Functions =====================================================================
//=== Main =================================================================================
//------------------------------------------------------------------------------------------

Nei file .h
//------------------------------------------------------------------------------------------
//=== Includes =============================================================================
//------------------------------------------------------------------------------------------
//=== Constants ============================================================================
//=== Function prototypes ==================================================================
//=== Type definitions (typedef) ===========================================================
//------------------------------------------------------------------------------------------

quando includiamo delle librerie segniamo come commento quali funzioni stiamo utilizzando

versione iniziale del 14-11-15