Convenzioni per la scrittura di codice Bash nei sistemi embedded

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.





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

I COMMENTI
I commenti presenti nei programmi saranno su tre livelli:

1. intestazione del modulo:
#!/bin/bash
#==========================================================================================
#
# 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
# <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. Scrivere i commenti prima del codice, scrivere cosa avete intenzione di fare seguendo quanto già scritto nei diagrammi

# Controllo che i parametri inseriti siano validi, altrimenti visualizzo
# un messaggio di errore e termino lo script
#
# TODO: scrivere il codice

# utilizzo dei nomi più comprensivi per i parametri inseriti 
Ora=$1
Nome=$2

NOMI
- Utilizzare nomi chiari ed autoesplicativi, evitare l'utilizzo di nomi var, x, i, ...
- Per i nomi usare la notazione CamelCase
- i nomi delle costanti sono con tutti i caratteri maiuscoli e separati dal carattere underscore (_)

INDENTAZIONE
Ogni volta che inizia un blocco di codice (if, while, funzione, ecc. ) il codice va indentato di una tabulazione usando il tasto tab oppure di due spazi

-------------------------------------------------------------------------------------------------------------
versione iniziale del 04.04.16