Abbiamo tre possibilità per commentare il codice in c#.

• // commenti in una sola riga
  
• /* commenti su più righe */
  
• /// Commenti per la generazione della documentazione XML
  

I primi due sono classici in molti linguaggi e non verranno discussi oltre.

Sul terzo tipo di commento si baserà questo capitolo.

Documentazione XML

Iniziamo con un esempio:

using System;
namespace Sample
{
  /// <summary>
  /// Un programma di esempio
  /// </summary>
  public class Sample
  {
    /// <summary>
    /// L'entry poit dell'applicazione
    /// </summary>
    public static void Main()
    {
      int a = 1;
      int b = 1;
      int c = 0;
      c = somma(a, b);
      Console.WriteLine("risultato = " + c);
    }
    /// <summary>
    /// Metodo per effettuare la somma di due interi
    /// </summary>
    /// <param name="a">primo operando</param>
    /// <param name="b">secondo operando</param>
    /// <returns>In risultato dell'operazione</returns>
    private static int somma(int a, int b)
    {
      return a + b;
    }
  }
}

Per generare la documentazione xml possiamo:

• utilizzare l’opzione /doc nel compiltatore a riga di comando
• se si usa visual studio, dalle proprietà del progetto (sezione configurazione), indicare ne campo “File di documentazione XML” il percorso del file che si vuola trovare.

Ecco la documentazione generata:

<?xml version="1.0" ?>
  <doc>
    <assembly>
      <name>ConsoleApplication1</name>
    </assembly>
    <members>
      <member name="T:Sample.Sample">
        <summary>Un programma di esempio</summary>
      </member>
      <member name="M:Sample.Sample.Main">
        <summary>L'entry point dell'applicazione</summary>
      </member>
      <member name="M:Sample.Sample.somma(System.Int32,System.Int32)">
        <summary>Metodo per effettuare la somma di due interi</summary>
        <param name="a">primo operando</param>
        <param name="b">secondo operando</param>
        <returns>In risultato dell'operazione</returns>
      </member>
    </members>
  </doc>

Possiamo notare che sono stati inseriti dei tag particolari come <summary> o <returns>, questi tag consentono di specificare delle tipologie diverse di informazione. <summary> ad esempio è la descrizione dell’elemento che stiamo commentando.

Vediamo una tabella con i tag utilizzabili

Tag	Descrizione
<summary>	Una descrizione generica di un metodo, una classe o altro
<remarks>	informazioni addizionali
<param name="name">	permette di specificare i parametri passati ad un metodo
<paramref name="name">	permette di specificare che una determinata parola è un parametro
<returns>	il valore di ritorno del metodo
<exceptions cref="type">	permette di specifire le eccezioni che possono verificarsi
<permission cref="type">	permette di specificare il livello di accesso
<value>	consente di descrivere una proprietà
<example>	specifica un esempio relativo all’utilizzo del codice
<c>	il testo deve essere identificato come codice
<code>	più righe devono essere identificato come codice
<para>	Si può inserire all’interno di alcuni tag come <summary>, <remarks> o <returns>, e permette di aggiungere una struttura al testo.