do more with less
news, esperienze, esempi da condividere e qualcosa su di me

domenica 10 settembre 2006

Commentare il codice con gli snippet di Visual Studio 2005

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:

 

<?xml version="1.0" encoding="utf-8" ?>
<CodeSnippets xmlns="http://schemas.microsoft.com/VisualStudio/2005/CodeSnippet">
<CodeSnippet Format="1.0.0">
<Header>
<Title>prop</Title>
<Shortcut>prop</Shortcut>
<Description>Code snippet for property and backing field</Description>
<Author>Microsoft Corporation</Author>
<SnippetTypes>
<SnippetType>Expansion</SnippetType>
</SnippetTypes>
</Header>
<Snippet>
<Declarations>
<Literal>
<ID>type</ID>
<ToolTip>Property type</ToolTip>
<Default>int</Default>
</Literal>
<Literal>
<ID>property</ID>
<ToolTip>Property name</ToolTip>
<Default>MyProperty</Default>
</Literal>
<Literal>
<ID>field</ID>
<ToolTip>The variable backing this property</ToolTip>
<Default>myVar</Default>
</Literal>
</Declarations>
<Code Language="csharp"> <![CDATA[private $type$ $field$; public $type$ $property$ { get { return $field$;} set { $field$ = value;} } $end$ ]]> </Code>
</Snippet>
</CodeSnippet>
</CodeSnippets>

Ora modifichiamo l'elemento <Title> inserendo un titolo nuovo, per esempio propc:


 


<Title>propc</Title>

 


Quindi è la volta dell'elemento <Shortcut> per modificare la combinazione di lettere con la quale vogliamo richiamare il nostro snippet:


<Shortcut>propc</Shortcut>

infine non ci resta che modificare il contenuto della sezione CDATA dell'elemento Code:


<Code Language="csharp">
<![CDATA[
/// <summary> /// Campo privato $field$ /// </summary>
private $type$ $field$;
/// <summary> /// Imposta/ritorna la proprietà $property$ /// </summary>
public $type$ $property$
{
get { return $field$;}
set { $field$ = value;}
}
$end$ ]]>
</Code>

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.