Commenti al codice

Quando scrivi del codice, ti abituerai al fatto che tutte le parole o i caratteri che inserisci avranno un significato particolare. Per esempio, vedrai tante keywords in C#, come class, namespace, public e tante altre. Vedrai anche come il compilatore controllerà che tu abbia usato queste parole nella maniera corretta. C# è un linguaggio abbastanza rigido e il compilatore ti aiuterà a inserire tutto nel modo in cui deve essere. In ogni caso, hai la possibilità di scrivere quel che vuoi grazie al concetto di commenti al codice.

Li avrai già incontrati in qualche riga di codice che hai visto, che sia C# o in qualunque altro linguaggio di programmazione - il concetto di commento nel codice è universale. Il modo in cui sono scritti però cambia parecchio, quindi diamo un occhio ai tipi di commenti che puoi usare nel tuo codice C#.

Commenti in una singola riga

Il tipo di commento più comune è il commento in una singola riga. Come lo stesso nome dice, fa di una riga un commento - vediamo:

// My comments about the class name could go here...
class Program
{
    ......

Ed ecco: inserisci due barre all'inizio delle tue righe e il testo va da essere controllato dal compilatore (con gli eventuali errori di sintassi del caso), a qualcosa che viene completamente ignorato. E visto che questo si applica solamente alla riga specifica, sei libero di fare la stessa cosa con la riga successiva, per fare molti commenti su diverse singole righe:

// My comments about the class name could go here...
// Add as many lines as you would like
// ...Seriously!
class Program
{
    ...... 

Commenti su più righe

Nel caso in cui vuoi scrivere più righe commentate, potrebbe avere più senso usare la variante di commento su più righe offerto dal linguaggio C#. Invece di avere il prefisso per ogni riga, inserisci un carattere di inizio e di fine sequenza - tutto quello in mezzo viene trattato come commento:

/*  
My comments about the class name could go here...  
Add as many lines of comments as you want  
    ...and use indentation, if you want to!  
*/  
class Program  
{
    ......

Per sequenza iniziale usiamo barra e asterisco (/*), così scrivi quel che vuoi, e infine inserisci la sequenza finale asterisco e barra (*/). Quindi, tra queste due sequenze potrai inserire quello che vuoi, che sia su una sola riga o su molte non importa.

Come per quasi tutti gli altri argomenti correlati alla programmazione, la decisione se usare più commenti su riga singola, oppure uno multiriga è spesso oggetto di discussione. Personalmente uso entrambe le modalità a seconda della situazione, alla fine la scelta è tua!

Commenti di documentazione

Commenti di documentazione (o anche commenti di documentazione XML) assomigliano a commenti normali, ma sono inseriti in un contesto XML. Allo stesso modo dei commenti normali, ce ne sono di due tipi: a singola riga, a riga multipla. Li scrivi allo stesso modo, però aggiungendo un carattere in più. Così, quelli a singola riga usano tre barre (///) invece di due, e la multi-riga aggiungono un asterisco nella sequenza di partenza.

class User
{
    /// <summary>
    /// The Name of the User.
    /// </summary>
    public string Name { get; set; }

    /**
    * <summary>The Age of the User.</summary>
    */
    public string Age { get; set; }
}

Puoi vedere entrambe le varianti - singola riga e riga multipla. Il risultato è lo stesso, ma la prima variante è quella più usata nei commenti di documentazione.

Elencare i tipi e i membri nei commenti di documentazione è un argomento parecchio intricato, e verrà così spiegato più in dettaglio in un articolo specifico più avanti, però almeno sai come sono fatti!

Commenti al codice & la lista delle Attività

Se stai usando Visual Studio, puoi ottenere un aiuto per tenere traccia dei tuoi commenti al codice. Nella finestra "Task List" (a cui puoi accedere dal menu Visualizza > Elenco attività ) i tuoi commenti appariranno se usano una speciale, ma molto semplice, sintassi "Elenco attività".

//TODO: Change "world" to "universe"
Console.WriteLine("Hello, world!");
//HACK: Don't try this at home....
int answerToLife = 42;

Quindi, se il commento su riga singola è immediatamente seguito da TODO oppure HACK, apparirà nella Task List di Visual Studio, in questo modo:

Ci sono altri tipi, a seconda della versione di Visual Studio che stai usando, risponderà a qualche oppure a tutti i seguenti commenti:

• TODO
• HACK
• NOTE
• UNDONE

Se vuoi, puoi anche aggiungere tu dei tipi, basta seguire i passi descritti in questo articolo.

Sommario

I commenti sono estremamente utili per documentare il tuo codice con l'obbiettivo di lasciare indizi a te stesso o a potenziali colleghi su come funzioni il codice. Come beneficio aggiunto sono ottimi quando hai bisogno di testare qualcosa velocemente, basta copiare una riga e commentare la riga originale per vedere come funzioni. Se non sei contento col risultato basta cancellare la nuova riga e togliere il commento all'originale per tornare al punto di partenza.

Non temere che l'utente finale guardi i tuoi commenti dato che sono, come abbiamo già menzionato, completamente ignorati dal compiler e non verranno inclusi nel file DLL o EXE finale. I commenti sono il tuo spazio personale quando programmi, usali in qualsiasi modo tu voglia.