Aggiungere le “linee guida” di sviluppo nel codice…

Recentemente sto sperimentando qualche aggiunta alla “documentazione” standard: le “linee guida” dello sviluppo e dell’implementazione di un progetto.

Sono sempre più dell’idea che la documentazione “implementativa” è così importante che mantenere dei file di documentazione esterni al codice per spiegarlo non sempre sia la scelta migliore: se cerco qualcosa riferito al codice il primo posto dove lo cercherò è nel codice stesso.

Trovarlo “inlined” è una manna dal cielo: dopotutto si tratta di commenti e informazioni tecniche, ad uso e consumo dei soli sviluppatori e di pochi altri “avventurieri”. Per cui farlo trovare dove i “destinatari” se lo aspettano è un favore enorme per questi ultimi.

1. Stampe evitabili

Non c’è nulla di più noioso che dover tener sott’occhio il codice e la sua “spiegazione” separata da esso. Si sa come va a finire in questi casi: si stampa la documentazione (quanta carta buttata…) per “tradurre” e capire il codice.

Sono assolutamente certo che se tutti gli sviluppatori scrivessero API con interfacce comprensibili e le accompagnassero una per una da piccolissimi snippet di codice di esempio “to the point“, tanta povera ed inerme carta verrebbe risparmiata.

Perchè devo sorbirmi 50+ righe di codice per vedere come usare dal vivo una determinata funzione all’opera, quando mi basterebbero giusto quelle 2-3 righe veramente essenziali per capirne il funzionamento? Perchè l’unico modo per “capirci qualcosa” da questi mega-esempi deve per forza essere stamparli?

Per tornare coi piedi per terra: detesto gli esempi lunghissimi e “comuni a più funzioni” di MSDN (ossia ne scrivono uno lungo, referenziato in più pagine e che mostra 1000 funzioni al lavoro contemporanemente e per giunta in mille linguaggi!).

Al contrario, quando devo devo cercare qualcosa nella documentazione delle librerie Qt sul sito di Nokia o direttamente in QtCreator, “godo intrinsecamente“. Finora il mio personalissimo ratio “trovati/cercati” è prossimo a 1:1 e scusate se è poco. Inoltre molte pagine includono snippet pronti all’uso, una sorta di frequently used examples/snippets, tremendamente comodi (cfr. gli “esempi” di questa funzione delle caselle di testo).

2. Linee guida del codice

Una cosa che ho molto apprezzato delle sopra-citate librerie (non solo in quelle a dire il vero, ma ultimamente le sto impiegando parecchio per cui le citerò spesso) e che in qualche modo mi ha “ispirato professionalmente” sono le pagine di documentazione “extra”: in particolare quelle che ad esempio fissano, spiegano e motivano le linee guida adottate in tutto il codice.

Non parlo del “come” scrivere il codice (“coding styles/rules/conventions”), quanto del “perchè” è stato scritto in quel modo.

In pratica l’autore spiega parte del suo operato ma senza porsi troppo sulla difensiva: le scelte adottate come conseguenza di necessità particolari, contesti, preferenze personali e tecniche, motivi “storici”, obblighi, …

Il tutto ha la forma di una piccola trattazione tecnica però è scritta in un linguaggio naturale (occhio alla grammatica!) e include citazioni (mai ripetere qualcosa già esistente!), riferimenti, delucidazioni, … tutto quello che un lettore può trovare comodo.

Un esempio per così dire “famoso”: “Why Doesn’t Qt Use Templates for Signals and Slots?“. Leggendola si capisce un po’ della filosofia alla base di questa scelta e, di conseguenza, quando ci si trova a che fare con signal/slot, già si sa dove si andrà a parare.

Ora, tornano al confronto citato poc’anzi, anche la MSDN contiene pagine di questo genere tuttavia trovarle è veramente complicato perchè risultano letteralmente sommerse da tonnellate e tonnellate di altre pagine.

Lo ripeto: poca documentazione e troppa documentazione alla prova dei fatti sono situazioni tanto negative quanto equivalenti.

Noto con piacere che svariati progetti OpenSource hanno pagine di documentazione sulle linee guida dello sviluppo, sulle scelte prese e sulle relative motivazioni.

1+2. Linee guida nel codice

Mettendo insieme i primi due punti, per magia compare ciò che sto provando a fare: scrivere le linee guida dello sviluppo direttamente nel codice.

Non sto impazzendo: parlo di spiegare scelte implementative direttamente nel codice, in apposite “pagine-commento” opportunamente marchiate con “tag” appositi di Doxygen come @page.

Come guardacaso fanno le stesse Qt (l’ho detto che mi hanno ispirato, no?).

Penso che sia un ottimo modo sia per:

1. dimostrare all’eventuale lettore-sviluppatore che non si è totalmente pazzi nè si fanno le cose a caso;
2. rinfrescarsi periodicamente la propria memoria sulle regole che ci si è dati e poter così mantenere un’alta coerenza nello sviluppo
3. avere un punto di riferimento chiaro anche per eventuali new entry nel progetto;
4. avere eventualmente qualcosa di comprensibile anche per i non-tecnici;
5. ecc…

Un esempio, in italiano e in stile JavaDoc (il mio preferito):

/**
 * @page GuideLines Linee guida adottate nel progetto
 *
 * 1) Nel progetto si è scelto di non usare i puntatori se non quando strettamente.
 *    necessario. Al loro posto verranno usati i "reference" che, fra le altre cose, non 
 *    possono essere nulli nè essere reimpostati ("reseat") in un secondo momento 
 *    per riferirsi ad altro.
 *    - REF: http://en.wikipedia.org/wiki/Reference_%28C%2B%2B%29   
 *
 * 2) ...  
 */

/**
 * Autore: Gian Paolo Ghilardi
 * File: main.cpp
 * [...]
 */

// [segue codice di main.cpp]

Ovviamente queste informazioni vanno infilate all’inizio di “main.cpp” (ci si aspetta che tutto parta lì), prima ancora dell’intestazione vera e propria del file (nome file, autore, …).

In alternativa, si può metterle in un file header a parte (così che Doxygen lo consideri) e con un nome che attiri l’attenzione: ad esempio readme.h, about-this-project.h o anche project-guide-lines.h.

Se volete, al posto di @page potete usare @mainpage che permette di modificare l’eventuale pagina index.html, nel caso di documentazione esportata in formato HTML.

Doxygen supporta davvero molti tag, alcuni dei quali permettono di creare documenti più complessi, con tanto di sottopagine, sezioni, …

Se poi vi servisse qualcosa di presentabile/stampabile, basta lanciare Doxygen sull’intero progetto ed ecco che vi troverete, ad esempio, con delle belle pagine HTML addizionali, utili ed autoesplicative.

In pratica la documentazione è acclusa al codice ma può essere “estratta” quando serve.

Un po’ come usare i tag LaTeX nel codice Matlab (troppo comodo), da cui poi si può ricavare un pratico PDF…

Che ne pensate?

Ciau! ^^