Sugli esempi da allegare al codice…

In passato ho parlato spesso di quanto la documentazione sia parte essenziale di qualunque progetto e di quanto i commenti al codice siano essenziali a comprenderlo. Tuttavia, credo, sarebbe pressapochistico limitarsi a questi soli due aspetti.

Sono ciò sempre più convinto che il successo di un qualunque progetto sia anche negli esempi di utilizzo: sia che si tratti del codice sorgente che di prodotto finito non c’è nulla di più diretto per spiegare qualcosa che mostrarla dal vivo, in azione attraverso degli esempi concreti di utilizzo.

Eppure ciò non capita spesso, purtroppo.

Restringiamo il fulcro della questione

Per evitare di parlare del nulla, vorrei concentrare la mia critica sui progetti software che in qualche modo agiscono come componenti tramite cui costruire altri progetti: è il caso, ad esempio, delle numerosissime librerie che un programmatore può includere e riutilizzare nei suoi progetti, ottimo esempio di programmazione modulare e quindi riutilizzo del codice.

Di solito, a fianco del codice sorgente e/o degli eventuali binari pronti all’uso (es: dll), si ritrova la relativa documentazione e, abbastanza spesso, degli esempi di utilizzo (es: sotto forma di samples completi oppure di semplici snippets). Il problema è che non sempre questi esempi sono davvero utili, quando ci sono.

Mi riferisco al fatto che non bastano nè servono pochi e complicati esempi tuttofare, che mostrano in un solo colpo come utilizzare al 100% una data libreria. Cioè se questa fornisce supponiamo 10 distinte caratteristiche, trovarsi un solo esempio di codice che le usa tutte e 10 contemporaneamente diventa un’esperienza oltremodo complicata per chi poi dovrà utilizzarla: non state facendo un favore a nessuno.

Se progettate un qualunque programma o libreria che qualcun altro poi dovrà utilizzare, per favore ricordatevi di: allegare documentazione, commenti ed esempi; inserire esempi piccoli, sufficientemente comprensibili, riusabili veramente e mostrare in modo preciso una o pochissime funzionalità per volta; aggiungere esempi di diversa e crescente livello di difficoltà: evitate di inserire solo esempi per utenti esperti o smaliziati e, piuttosto, favorite nel numero gli esempi per i programmatori di livello medio-basso; commentare e documentare gli esempi stessi.

Tengo molto all’ultimo punto: non c’è niente di peggio di un esempio che non si riesce a decifrare, figuriamoci a comprendere e riutilizzare con profitto. Di contraltare apprezzo moltissimo gli esempi ottimamente documentati , meglio ancora quelli che sfruttano l’approccio step-by-step, arrivando a descrivere riga per riga quello che fa il codice e, nel caso, perchè si fanno le cose in quel particolare modo.

Gusti personali a parte, gli esempi possono tornate estremamente utili anche a chi li scrive. Individuo principalmente due motivi per cui scrivere e mantenere gli esempi di utilizzo risulta vantaggioso.

L’esempio come test

Se il primo uso di una tua libreria è un tuo esempio, significa che come minimo avrai verificato che tutto funzioni correttamente, in ossequio al cosidetto dogfood principle, conosciuto anche come eat your own dog food, citato dall’amico Stefano in un suo recente post e così sintetizzato dal solito Spolsky:

“The term “eating your own dogfood,” in the software industry, means using the code you’re developing for your own daily needs: basically, being a user as well as a developer, so the user empathy that is the hallmark of good software comes automatically.”

Addirittura l’esempio accluso alla libreria potrebbe contenere test particolari (es: unit-test) in modo che cambiando troppo la libreria, otterrei dei fallimenti in alcuni di essi: sostanzialmente l’esempio è esso stesso un test di qualità per la libreria a cui si riferisce.

Se pensate che quanto ho detto sia banale, potete ritenervi fortunati: non di rado mi sono capitati e capitano sotto mano esempi di codice che non si compilano proprio (argh!) o non sono stati aggiornati/mantenuti nel tempo o ancora sono stati scritti ma mai veramente collaudati (sostanzialmente sono delle specie di consigli spannometrici, non esempi veri e propri).

un rilascio è completo se e solo se tutto funziona: se anche solo un piccolo esempio non compila, non rilasciate nulla prima di averlo corretto o preparatevi all’ira dell’eventuale utilizzatore; siete autorizzati e caldamente invitati a diffidare di chi vi fornisce il codice ma non esempi di utilizzo adeguati, comprensibili e riimpiegabili con successo senza troppa fatica.

L’esempio come best-practice

Alzi la mano chi non ha mai preso del codice da un esempio, provato a compilare e se funzionava nel modo atteso/sperato, riutilizzato nei propri progetti (*).

L’esempio del codice per definizione è un modello di come qualcosa dovrebbe essere usata, è una specie di best practice implicita per cui bisognerebbe prestare molta attenzione alla sua qualità. Chi scrive una libreria e acclude degli esempi si assume la responsabilità morale anche per gli errori in questi ultimi.

Non c’è nulla di peggiore di trovare degli esempi raffazzonati o addirittura scritti male ed insicuri.

Non troppo tempo fa, giusto per dire, mi sono ritrovato a seguire un esempio di codice relativo ad una libreria C/C++. Tutto sommato l’esempio era chiaro, discretamente commentato e documentato ma, alla fine, non liberava la memoria allocata in precedenza oppure lo faceva in modo vistosamente errato.

Quel tipo di “piccola svista ” nel codice di esempio – errare è umano, dopotutto – rischia di vanificare brutalmente l’impegno profuso nel realizzarlo, oltre a mettere potenzialmente nei guai chi poi lo deve utilizzare (*, nuovamente).

Questo perchè, di norma, ci si fida degli esempi, soprattutto quando si ha fretta di finire un lavoro. Scoprire che un esempio è sbagliato significa dover rimettere in discussione tutti gli esempi e di rimando, l’intera libreria.

piuttosto di rilasciare qualcosa di raffazzonato o di cui voi stessi non vi fidate, posticipate i rilasci; basta veramente poco per perdere la fiducia di chi usa il vostro codice: se la perdete, addio possibilità di successo per voi e per la vostra libreria.

Che ne pensate?

(*): tutti lo fanno o l’hanno fatto in passato. Tuttavia, la differenza fra un buono ed un cattivo programmatore sta nel fatto che il primo prende il codice dall’esempio, lo gira e lo rigira per adattarlo allo stile ed alla qualità del proprio. Il secondo semplicemente prende il codice è lo butta così com’è nel suo “impasto”.