Quanto è importante commentare il codice che scriviamo? La prima risposta che mi viene in mente è "moltissmo" ma allargando il punto di vista direi "dipende". Ma da cosa dipende? Sicuramente dal contesto in cui stiamo scrivendo il codice e da che uso ne verrà fatto. Quando scriviamo solo per noi l'inserimento di commenti nel codice è spesso frutto di abitudine a farlo ma non è dettato da esigenze specifiche. Diverso invece dovrebbe essere l'approccio quando il codice è destinato ad essere utilizzato anche da altre persone (esempi per le community, post nei newsgroup, tips, ecc).
C'è però un caso in cui ritengo indispensabile commentare il codice: lo sviluppo professionale. Questo è maggiormente vero se si sviluppa all'interno di un team in cui si deve garantire continuità di manutenzione ed interoperabilità tra i membri del team. Sembra una banale constatazione, non è vero? In realtà non è così. Chiunque abbia mai ricoperto la posizione di program manager, project manager o team leader conosce bene il problema e sa come sia difficile sensibilizzare gli sviluppatori affinché commentino il proprio codice. Spesso si è costretti a prevedere sessioni di code review per inserire i commenti mancanti e si spendono molte parole durante i meeting settimanali nel ricordare l'importanza di questo requisito.
Ma i benefici sono reali? Si lo sono. Pensate a quando riprendete in mano del codice scritto un pò di tempo prima. Vi ricordate subito cosa faccia? Quando vi capita di manutenere il codice scritto da altri non vi è mai capitato di pensare: "...ah se almeno chi l'ha scritto avesse inserito un commento."? Senza contare che dai commenti è possibile costruire con poca fatica e con i tool appositi (nDoc, DocToHelp, Sandcastle, ecc) delle reference al nostro codice in diversi formati.
Ma cosa c'entra questo con il titolo di questo post? Ok, arrivo al dunque. Usando gli snippet di Visual Studio, appositamente modificati, ho notato che anche i più recidivi e pigri, hanno iniziato ad inserire i loro commenti. Questo non risolce il problema ma gli snippet aiutano a creare l'abitudine a farlo e conseguentemente a ridurre i problemi legati alla mancanza di commenti nel codice.
Vediamo un esempio concreto. Partiamo dallo snippet prop.snippet fornito con Visual Studio 2005:
Ora modifichiamo la righa 5 <Title> inserendo un titolo nuovo, per esempio propc:
Quindi è la volta della riga 6 per modificare la shortcut con la quale vogliamo richiamare il nostro snippet:
infine non ci resta che modificare il contenuto della sezione CDATA dell'elemento Code posto alla riga 31:
Come si può notare, ho semplicemente inserito la parte di commento richiesta per la proprietà e per il campo privato.
Ora non resta che salvare lo snippet modificato con il nome propc.snippet nella directory che preferiamo (normalmente si usa la directory C:\Documents and Settings\[User]\My Documents\Visual Studio 2005\Code Snippets\Visual C#\My Code Snippets) e far si che Visual Studio la utilizzi impostando i riferimenti con Code Snippet Manager (ctrl +K, ctrl +B).
In questo modo, richiamando lo snippet propc direttamente da Visual Studio 2005 verrà generato il codice con la struttura di commento già predisposta. Al programmatore non resterà che modificare il contenuto del commento base adattandolo al caso.
Questo è un semplice caso ma fornisce un'idea di come procedere anche per i casi più complessi.
Maggiori informazioni su come gestire gli snippet si possono trovare qui: How to: Manage Code Snippets
Un utile tool per l'editing e la creazione di snippet è Snippy.