Programming Style Guideline 10¶

Premessa:
Ogni programma va prima progettato e poi realizzato. Prima di cominciare a scrivere definizioni o codice occorre aver deciso con precisione cosa si deve fare. Meglio se questo processo decisionale è scritto.¶

• Ogni sorgente deve cominciare con un commento. Questo commento iniziale deve contenere:
  1. Nome, cognome di tutti i componenti del gruppo
  2. Data di inizio della stesura del programma
  3. Nome del file, per garantire chiarezza nella stampa
  4. Testo del problema, scritto in maniera più chiara e descrittiva possibile
  5. Assunzioni aggiuntive o limitazioni del programma
  6. Eventuali note sugli algoritmi usati

• Ogni sorgente dovrà contenere nell'ordine:
  1. Commento iniziale
  2. Istruzioni #include per tutti i file da includere (attenzione! includere solo i file necessari)
  3. Dichiarazioni di costanti, strutture e tipi enumerativi
  4. Definizione di variabili
  5. Prototipi delle funzioni
  6. Definizione delle funzioni

La funzione main va messa come prima funzione.

• I nomi delle variabili, strutture, costanti e funzioni devono essere significativi.
• Sono da evitare nomi troppo lunghi. È opportuno cercare in linea di massima di contenere la lunghezza dei nomi sotto i 16 caratteri.
• Se un nome deriva dalla concatenazione di più parole è preferibile evidenziare con iniziali maiuscole le parole seguenti alla prima, piuttosto che usare il carattere _, che aumenta la lunghezza del nome, per separarle.
• I nomi delle costanti vanno scritti tutti in maiuscolo (in questo caso usare gli _ per separare le parole, se il nome è composto)
• I commenti sulla stessa riga delle costanti vanno fatti con /* ... */ e non con // .... perchè alcuni compilatori sostituiscono l'intera riga della costante, compreso il commento, generando errori difficili da rintracciare.
• Se una costante non è costituita solamente da un valore semplice, ma da un'espressione (come ad esempio #define TOTALE (A+B)) ricordarsi di mettere tra parentesi l'espressione, come nell'esempio. A TOTALE viene sostituito il testo che segue. Se noi, per esempio, adesso calcolassimo x=TOTALE*2, con le parentesi risulta correttamente x=(A+B)*2, ma senza sarebbe diventato x=A+B*2, che viene calcolato come x=A+(B*2), quindi errato.
• I nomi di strutture, variabili, funzioni o altro vanno scritti tutti in minuscolo, salvo per le iniziali, come indicato precedentemente.

• Nelle dichiarazioni di tipi (struct, union, enum) o nei costrutti (if, else, while, switch ..) nelle inizializzazioni di variabili all'interno delle definizioni la { che apre il blocco va posta di seguito al nome del tipo all'uguale dell'inizializzazione, sulla stessa riga.
  Nel caso delle struct o union, i vari campi andranno su righe separate, indentati rispetto alla dichiarazione, mentre la graffa di chiusura andrà allineata con l'inizio della dichiarazione, su di una riga a sè stante.
  Per gli enum e le inizializzazioni, se trovano posto sulla stessa riga della dichiarazione stessa, andranno chiusi con la graffa sulla stessa riga, altrimenti andranno indentati e su righe successive, con la graffa su una riga a sè stante, allineata con la definizione.
• Le variabili globali vanno usate solo se strettamente indispensabile.
• Per ogni costante, ogni struttura, ogni campo di struttura ed ogni variabile locale occorre indicare, con un commento, la sua funzione.
• Le dichiarazioni di variabili locali vanno allineate esattamente sotto la { di apertura del blocco in cui sono definite.
• Anche se il C++ lo consente, le variabili locali non vanno definite nel punto del primo utilizzo (ad esempio la variabile del for definita nel for stesso) ma all'inizio del blocco in cui sono utilizzate.
• Tutte le istruzioni contenute in un blocco vanno indentate rispetto all'allineamento del blocco stesso (che sia la { di apertura o il do).
• Una funzione deve eseguire un compito. Non è opportuno scrivere funzioni che contengano il codice per fare molte cose assieme. Piuttosto, scrivere le funzione per i singoli compiti ed una ulteriore funzione che svolga il compito complesso, invocando le funzioni precedenti.
• Le funzioni comunicano con il resto del programma tramite i parametri ed il valore di ritorno. In particolare i parametri vanno normalmente dal programma alla funzione ed il valore di ritorno dalla funzione al programma. Se l'interazione non è questa, occorre documentarlo molto bene. In particolare:
  • Se una funzione modifica delle variabili globali
  • Se una funzione ha dei parametri passati per riferimento che vengono modificati

• Attenzione che i vettori e le strutture sono sempre passati per riferimento alle funzioni, quindi occorre documentare molto bene il loro uso. Sarebbe auspicabile usare la parola chiave const per i parametri (strutture o vettori) in ingresso. Se si usano i prototipi per le funzioni, indicare sempre i nomi dei parametri, oltre ai tipi. I tipi servono al compilatore, i nomi al programmatore. Inoltre, commentare ogni prototipo indicando il compito della funzione ed i parametri usati. Questo commento deve essere più sintetico di quello prima della definizione della funzione. Si deve puntare a descrivere più la funzione che i parametri. Meglio se il commento è breve e sta sulla stessa riga del prototipo.
• Prima di ogni funzione, eccetto che per il main, è necessario fare un commento, molto evidente (per individuare alla svelta le funzioni, quando le si cerca), che contenga:
  • Scopo della funzione
  • Significato e valori leciti dei parametri, uno per uno
  • valori di ritorno nei vari casi
  • Eventuali parametri passati per riferimento modificati all'interno della funzione
  • Eventuali effetti collaterali sulle variabili globali

• I commenti devono essere sintetici. Le istruzioni devono comunque essere la cosa che spicca maggiormente nella lettura; il compito dei commenti è di renderle ancor più comprensibili, non di sommergerle.
• I commenti devono essere aggiornati. Se modifichiamo l'uso di una variabile o l'algoritmo di una funzione e non modifichiamo il commento che lo spiega, invece di rendere più facile la comprensione il commento la ostacolerà.
• I commenti vanno separati di almeno uno spazio od una tabulazione dall'istruzione che descrivono.
  Se il commento inserito dopo l'istruzione è troppo a destra, è bene spostarlo sulla riga precedente, allineato con l'istruzione.
• Quando l'algoritmo utilizzato in una funzione non è evidente è necessario documentarlo molto bene con un commento sufficientemente esteso.