Commenti e stile

Dal mio manuale di programmazione (LISP Trek, 2007) voglio citare alcune pagine scritte sull’uso dei commenti e dello stile in programmazione. Anche in queste povere pagine ingenue, scritte nell’ormai lontano e mitico dicembre 2006, sono contenuti molti miei tic e manie, forse anche una profezia, insomma cose così, molto superficiali, ma le stesse pagine potranno essere lette estraendo un modo di vivere formale, che è sempre più minoritario nel nostro cosiddetto vivere civile.

Commenti

Il Novellino dà l’impressione di un solaio narrativo nel quale si può trovare di tutto, squisitezze e schegge inservibili, una spada di Toledo, una vecchia macchina da scrivere, un fantasma che ha disimparato a parlare, l’ultima salma impagliata di un animale definitivamente scomparso dalla faccia della terra. In ogni caso, questi oggetti estranei e ostili, giustapposti in un luogo appartato, hanno questo in comune, questo documento o testimonianza di un «autore»: sono tutti morti.
Giorgio Manganelli, Introduzione al Novellino.

Un commento è semplicemente una nota che spiega il codice sorgente nei punti salienti. È una buona consuetudine inserire commenti all'interno del codice sorgente dei programmi, e non solo per chi leggerà il codice ma anche per noi stessi, quando ci torneremo sopra, magari dopo un anno, a voler essere ottimisti, o una settimana. Non basta però scrivere i commenti nel codice sorgente; i commenti devono essere anche chiari, sensati ed utili. Sarà una raccomandazione ovvia, ma ho notato nel leggere i codici sorgenti, di programmi scaricati da Internet, che non sempre i commenti presenti sono utili; non lo sono ad esempio i commenti inseriti a pioggia, in modo meccanico, per precisare nomi di variabili in modo insulso, tipo «P sta per PIPPO» o per esternare al lettore i dubbi e le perplessità del programmatore: «ma questa variabile devo passarla per valore?». È inutile e maleducato inserire commenti sull’intelligenza del lettore; è inutile inserire un commento alla fine di un ciclo condizionale per sottolineare la fine dello stesso (inutile si intende se il codice è ben indentato, vedremo poi come in seguito), sempre che il ciclo condizionale non sia più lungo di una schermata video. Se il programma è in corso d’opera inserire commenti nelle parti del codice da perfezionare è fondamentale; in questa fase della vita del programma mettere in forma di commento pezzi del codice come alternative da sperimentare in futuro è molto utile. Però quando il programma eseguirà alla perfezione il compito assegnato ricordatevi di eliminare questi pezzi di codice in forma di commento. Perché la presenza di questi commenti all’interno di codici spacciati per definitivi non solo è illogico ma sa pure di sciatto (ma un programmatore di indole poetica sosterrebbe che questi morti frammenti di codice sorgente sono come un «solaio narrativo» al di sopra delle stanze abitate del programma).
Un commento in LISP inizia con il segno ; tutto ciò che segue questo segno, nella stessa riga, non è letto dall’interprete LISP. È possibile inserire più righe di commento facendo precedere ogni riga dal segno. E alla fine del programma, dopo l’ultima parentesi chiusa, è buona regola scrivere:

;;; End of file

o più semplicemente:

;;; eof

così siamo sicuri che il codice sorgente c’è tutto e non ne abbiamo perso un frammento per strada.

Stile

Premesso che alla base di un codice sorgente leggibile, da occhio umano, c'è una buona implementazione dell’algoritmo, per rendere comprensibile un codice sorgente non basta inserire commenti ma è essenziale indentarlo. Un codice sorgente con una buona indentazione è più leggibile, necessita di meno commenti superflui, e da un punto di vista umano è più funzionale. Infine una corretta indentazione consente di vedere facilmente se manca una parentesi all’appello. All'interprete LISP non interessa come si presenta il codice, per lui i seguenti listati sono uguali:

(defun test (arg / b c)
.(setq a “VG”)
.(setq b “VL”)
.(setq c arg)
.(setq c (* arg 2))
)

(defun test (arg / b c)
......(setq a “VG” b “VL” c arg)
......(setq c (* arg 2))
)

(defun test (arg / b c)(setq a “VG”)(setq b “VL”)(setq c arg)(setq c (* arg 2)))

Ma l'interprete LISP non è un essere umano. Tenuto conto che la difficoltà maggiore nel programmare in LISP sta nel parificare il numero di parentesi e delle virgolette doppie è quasi ovvio arrivare alla conclusione, più o meno per tutti, che una buona indentazione del codice sorgente non è un optional come non lo è la pelliccia per Lupo Alberto.
Il numero degli spazi di indentazione è invece una questione di gusti personali. Tuttavia siccome un programma LISP si sviluppa, o si avviluppa, in molteplici liste annidate, una singola spaziatura prima della parentesi aperta è sufficiente, perché già con due o tre spaziature le espressioni finirebbero fuori della pagina mostrata in video, rendendo faticosa la lettura del codice per i continui interventi del mouse sul cursore orizzontale.