TOC

This article is currently in the process of being translated into Italian (~81% done).

Le Basi:

Code Comments

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, se usare più commenti su riga singola, oppure uno multiriga è spesso oggetto di discussione. Personalmente uso entrambi in diverse situazioni, 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 dei processi

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 View > Task List) i tuoi commenti appariranno se usano una speciale, ma moltro semplice, sintassi "Task List".

//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 tipo, a seconda della versione di Visual Studio che stai usando, risponderà a qualcuno oppure atutti i seguenti commenti:

  • TODO
  • HACK
  • NOTE
  • UNDONE

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

Summary

Code comments are extremely useful in documenting your code or for the purpose of leaving clues to your self or your potential colleagues on how stuff works. As an added benefit, they're great when you need to test something quickly - just copy a line and comment out the original line and you can see how it works now. If you're not happy with the result, you can just delete the new line and uncomment the original line and you're back to where you started.

And don't worry about the end-user snooping through your comments - they are, as already mentioned, completely ignored by the compiler and therefore not in anyway included in your final DLL or EXE file. Code comments are your personal free-space when programming, so use it in any way you want to.

This article has been fully translated into the following languages: Is your preferred language not on the list? Click here to help us translate this article into your language!