Follow

Ultimamente, lo ammetto, sto scrivendo parecchio meno del solito. Sono oscillazioni naturali, non si possono avere sempre cose intelligenti da dire e in questo caso è meglio tacere piuttosto che scrivere diecimila post uguali sull’ultima emissione gassosa di Google o di chissà quale altro software. Ho passato le ultime settimane per lo più a studiare (anche se non al ritmo che mi aspettavo causa mancanza di fonti e concentrazione) e ad approfondire alcuni miei interessi. Siatene giulivi poiché dispenserò a breve tale conoscenza a fiotti sulle vostre menti assetate.

Ma torniamo a noi. Nell’ultima settimana mi sono trovato a mettere le mani sul sorgente di KPackageKit. Questo sorgente è un vero lavoro machiavellico di ingarbugliamento di idee, completamente privo di documentazione e saltuariamente infarcito di commenti di poco aiuto come granella di nocciola sul gelato. Allorché, in preda al deliro causato dall’essermi letto migliaia di righe di codice senza averci capito quasi nulla, se non a grandi righe, mi è venuta l’idea di buttare due righe su come NON si programma.

Ci sono infatti una manciata di cose che un programmatore non deve mai fare. Una lista di COSE DA NON FARE che troppo spesso vengono fatte al grido di “tanto funziona” e “tanto si capisce”. Risulta quindi più facile spiegarvi cosa non fare piuttosto che insegnarvi il contrario.

1) NON DOCUMENTARE IL CODICE

La risposta del tizio di KPK alla richiesta di documentazione è stata:

I don’t create documentation for KPackageKit because I think libs needs to be docummented, and if you read the lib’s docs you will understand KPackageKit

Permettetemi di dissentire. E’ normale che un programmatore debba conoscere la documentazione delle librerie Y alla base di un progetto X, ma ciò non toglie che anche il progetto X debba essere documentato! La documentazione di X infatti serve, come minimo, a spiegare come viene utilizzata la libreria Y all’interno di X. La documentazione serve per aiutare chi mette le mani sul codice per la prima volta, fornisce un filo rosso da seguire per muovere i primi passi all’interno del codice senza perdersi e in modo efficiente, spiega quali sono i moduli, il loro funzionamento e come sono relazionati fra di loro. Tutte cose che si possono apprendere dal codice ma che necessita di un enormità di tempo.

Questo fa quindi perdere tempo al novello programmatore e spesso perdere tempo significa far perdere la voglia.

2) DESCRIVERE IL CODICE

Altro errore frequente è quello di descrivere il codice nei commenti. I commenti devono descrivere le intenzioni di un passaggio non tutti i dettagli. Dovete infatti assumere che chi legge il codice conosca il linguaggio e gran parte delle librerie sottostanti.

/* COMMENTO ERRATO:

 * Se a è maggiore di b restituisce a, altrimenti b.

 */



/* COMMENTO GIUSTO:

 * Restituisce il più grande fra a e b.

 */

if (a > b)

    return a

else

    return b

Ora, quello sopra era un esempio piuttosto idiota ma spero sia chiaro il concetto. In sintesi i commenti dovrebbero descrivere tutto ciò che non è chiaramente intuibile leggendo il codice nei dintorni.

3) USARE CONVENZIONI AD-PERSONAM

Questo si traduce in un semplice usate le convenzioni del linguaggio. Questo va fatto sempre. Anche se una cosa è sintatticamente corretta non vuol dire che lo sia. Se nel linguaggio le classi cominciano per maiuscola NON fate classi che non cominciano per maiuscola. Questo serve a far subito capire ad altri programmatori il significato di una parola all’interno del codice. Se io leggo in un codice C++ la parola supereroe io penso che sia una variabile e non una classe. Se invece scrivete SuperEroe allora è chiaro che tale parola si riferisce ad una classe. Semplificando di molto il mio lavoro.

Oltre a questo le convenzioni di un linguaggio indicano la via corretta per molti altri aspetti. Se avete intenzione di infrangere delle convenzioni documentatelo. Come, ad esempio, fa Google con le linee guida per python.

4) NON MANTENERE UNA COERENZA INTERNA

Cosa più semplice a farsi che a dirsi ma che spesso viene del tutto ignorata. Un esempio di coerenza interna è la posizione dei parametri di un metodo o di una funzione oppure il nome delle funzioni. Se decidiamo che tutte le funzioni che accettano in ingresso un vettore finiscano con la lettera v allora dobbiamo accertarci di seguire questa regola per tutto il progetto. Se decidiamo che il primo parametro delle funzioni che si riferiscono ad una Persona sia il nome allora dobbiamo accertarci che sia sempre così.

5) LASCIARE BOLLE DI CODICE SOTTO COMMENTO

Può capitare che, nel corso della scrittura di un programma si commentino grandi parti di una funzione o interi metodi. Questo può servire ad isolare del codice buggato o a nascondere funzionalità incomplete. Tuttavia, sebbene questo vada bene in rami locali personali non dovrebbe mai essere lasciato in rami pubblici. Se una funzione funziona bene, altrimenti la togliamo. Queste bolle di codice creano gran confusione  e soprattutto un programmatore intento a modificare il codice se le ritrova in mezzo alle scatole senza sapere se le può togliere oppure no.

6) CHIAMARE LE VARIABILI CON UNA LETTERA O CON NOMI A CASO

I nomi delle variabili dovrebbero essere piuttosto esplicativi. Ad esclusione di contatori ed iteratori, una variabile non dovrebbe mai avere un nome di una sola lettere. A meno che l’oggetto a cui si riferisce non sia proprio un qualcosa identificabile da una lettera (ad esempio le coordinate x e y di un punto). Non vedo dove sia il problema a scrivere variabili di una decina di caratteri considerando che tutti gli editor hanno l’auto-completamento.

7) ORGANIZZARE IL CODICE SENZA CRITERIO

Il codice va diviso e organizzato in macro-moduli (o package, come si chiamano in molti linguaggi) che siano coerenti fra loro. Questo per consentire un rapido accesso all’insieme dei moduli che gestiscono una data funzionalità. Questi macro-moduli vanno assolutamente documentati.

8 ) SCRIVERE CODICE SENZA PROGETTO

Questo è il punto fondamentale. I programmi vanno prima scritti a computer spento. Non fatevi prendere dalla fretta di scrivere e compilare perché al 90% esce un casino. Questo può andare bene per piccoli progetti e roba semplice ma per qualunque cosa di complesso è un suicidio. Programmate tutto su carta. Scrivete le classi di cui avete bisogno, le relazioni fra le stesse, le operazioni salienti, i moduli da fare e i package in cui suddividerli. Dopo un paio di giorni di analisi a computer spento vedrete che con mezza giornata scriverete migliaia di righe di codice come se fossero sonetti in rima baciata.

Ovviamente mentre scriverete e proverete il codice sul serio salteranno parecchie cose di cui non avevate tenuto conto o errori di progetto. Ma non fa nulla. Questa è la prassi, è il modo in cui vanno fatte le cose.

CONCLUSIONE

Ora spero che appenderete questi 8 punti sulla vostra parete perché io non ho più voglia di impiccarmi mentre leggo del codice scritto e documentato da un macaco. 🙂 Se seguite i miei consigli e non fate questi 8 punti (in realtà potrebbero essere di più ma oggi sono buono) vedrete che sarà tutto più facile per voi, sia per chi ha intenzione di aiutarvi.

Buona giornata. 🙂