Moreno Marzolla research and teaching wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Suggerimenti per la scrittura di codice ======

È molto probabile che gli argomenti di tesi che propongo richiedano di scrivere del codice. Per questo motivo elenco alcuni suggerimenti per la scrittura di codice, che sebbene siano orientati principalmente al codice in linguaggio C, si possono applicare anche ad altri linguaggi.

:!: Una trattazione approfondita delle buone pratiche di programmazione è disponibile nella dispensa seguente:

  * M. Marzolla, [[https://www.moreno.marzolla.name/teaching/programming-style.pdf|Programmazione: una breve guida di stile]] 

**Si invita a leggere il documento con la massima attenzione**; quanto presente in questa pagina web è solo un sunto.

=== Rispettare lo standard del linguaggio ===

I programmi devono compilare correttamente senza warning (e ovviamente senza errori). Nel caso di programmi in C/C++ compilati con ''gcc'', ciò significa che i programmi devono compilare senza warning passando i flag ''-Wall -Wpedantic''. È sempre opportuno inoltre specificare lo standard che si vuole rispettare; ad esempio, se il proprio programma è scritto in C99, suggerisco di compilare con:

''gcc -std=c99 -Wall -Wpedantic ...''

Se invece si programma in ANSI C, suggerisco di usare:

''gcc -std=c90 -Wall -Wpedantic ...''

(esistono parametri analoghi per le varie versioni del C++).

=== Usare nomi di variabili appropriati ===

L'uso di nomi inappropriati rende il codice difficile da comprendere e da valutare). Per rendersi conto di ciò, chi direbbe che questa funzione:

<code C>
int cancella( double trovato, double tentativo[], int n, int terzo, int quarto )
{
    int box = (terzo + quarto) / 2;
    if ( tentativo[box] == trovato ) {
        return box;
    } else {
        if ( tentativo[box] > trovato ) {
            return cancella( trovato, tentativo, n, terzo, box – 1);
        } else {
            return cancella( trovato, tentativo, n, box + 1, quarto );
        }
    }    
}
</code>

in realtà non cancella nulla ma implementa la ricerca binaria? (Sì, mi è capitato di ricevere codice del genere...).

=== Commentare il codice in modo adeguato ===

È buona norma commentare adeguatamente il codice. Ciascuna funzione dovrebbe avere una intestazione che ne spiega il funzionamento, il significato dei parametri e il significato del risultato (se presenti). Non è indispensabile essere troppo dettagliati (anche se male non fa). Esempio:

<code C>
/**
 * Restituisce l'indice della prima occorrenza del valore
 * k all'interno dell'array a[] di lunghezza n; se k
 * non è presente in a[], restituisce -1.
 */
int prima_occ(int a[], size_t n, int k)
{
   /* ... */
}
</code>

Il corpo delle funzioni o metodi va commentato quando necessario per chiarire i punti che potrebbero risultare ostici. Si evitino accuratamente commenti inutili o ridondanti.

== Esempio di commenti inutili DA EVITARE ==

<code C>
v = v + 1;    /* incrementa v */
if ( v>10 ) { /* se v e' maggiore di 10 */
   v = 0;     /* setta v a zero */
}
Kruskal(G,v); /* esegui l'algoritmo di Kruskal */
</code>

== Esempio di commenti appropriati ==

<code C>
/* Individua la posizione i del primo valore
 * negativo nell'array a[] di lunghezza n; 
 * al termine si ha i == n se non esiste alcun
 * valore negativo.
 */
int i = 0;
while ( i < n && a[i] >= 0 ) {
    i++;
}
</code>

=== Indentare il codice in modo adeguato ===

Il codice deve essere indentato correttamente e in modo consistente. Per alcuni linguaggi esistono diversi stili di indentazione, e ciascuno di noi ha il suo preferito. Nel codice scritto da me tendo a seguire lo stile [[https://en.wikipedia.org/wiki/Indentation_style#K&R_style|K&R]], settando l'indentazione a multipli di 4 spazi. Tuttavia, sentitevi liberi di utilizzare il vostro stile preferito, purché venga seguito in modo consistente. Gli ambienti di sviluppo moderni (e anche quelli meno moderni...) consentono di indentare in modo automatico: consiglio di sfruttare questa caratteristica.

Se il proprio editor consente di scegliere, suggerisco di indentare usando spazi anziché caratteri di tabulazione. In questo modo il codice risulterà indentato allo stesso modo anche se viene visualizzato da qualcuno che ha impostato le tabulazioni in punti diversi.

=== Evitare linee più lunghe di 80 caratteri ===

Il codice dovrebbe essere leggibile su una finestra larga 80 caratteri. I monitor moderni sono molto più larghi, ed è facile lasciarsi prendere la mano utilizzando tutta la larghezza dello schermo. Così facendo, però, le righe di codice e i commenti risultano troncati, o vengono mandati a capo, se il codice viene leggo usando una finestra più stretta. 

L'ampiezza di 80 caratteri è [[https://en.wikipedia.org/wiki/Characters_per_line|un retaggio del passato]] che però risulta comodo per [[https://stackoverflow.com/questions/110928/is-there-a-valid-reason-for-enforcing-a-maximum-width-of-80-characters-in-a-code/111009#111009|diversi motivi]]:

  * Il codice non va a capo se viene incollato in un messaggio (solo testo) di posta elettronica;
  * Il codice risulta più leggibile rispetto al caso in cui si usino linee lunghe, dato che non è necessario spostare lo sguardo continuamente a destra e sinistra;
  * È possibile mantenere più finestre affiancate sui monitor moderni, se lo si desidera.

Si tenga presente che, sebbene i monitor moderni abbiano guadagnato risoluzione e dimensione, i nostri occhi sono rimasti sempre gli stessi.

=== Se possibile, rendere disponibile il codice con una licenza libera ===

Sebbene non indispensabile, suggerisco di rendere disponibile il proprio codice secondo una licenza libera. Alcuni esempi di licenze libere:

  * [[https://www.gnu.org/licenses/gpl.html|GNU GPL]], [[https://www.gnu.org/licenses/lgpl.html|LGPL]], [[https://www.gnu.org/licenses/agpl.html|AGPL]] (preferibilmente versione 3 o successive);
  * [[https://directory.fsf.org/wiki/License:BSD-3-Clause|BSD License]] (ne esistono diverse versioni);
  * [[https://creativecommons.org/|Creative Commons]] (usata prevalentemente per prodotti diversi dal codice sorgente; evitare se possibile la clausola "non-commercial").
  * [[https://opensource.org/licenses/MIT|MIT License]]

In [[https://opensource.org/licenses|questa pagina]] si trovano elencate ulteriori licenze comunemente usate. Personalmente tendo a preferire la licenza GPLv3+ (GPL versione 3 o successive), ma non impongo nessun vincolo a riguardo; si può anche decidere di non rendere il codice pubblicamente accessibile.

Se si intende usare una licenza libera, occorre inserire il sunto della licenza in un commento all'inizio di ogni file sorgente (ciascuna licenza ha il proprio "boilerplate"), e includere il testo completo della licenza in un file di testo (normalmente chiamato "LICENSE") nella directory radice dell'archivio contenente i sorgenti.