La documentazione del codice è una delle principali attività che deve essere fatta durante lo sviluppo del codice stesso. Avere una buona documentazione direttamente nel codice, spesso, fornisce un miglior risultato rispetto alla documentazione cartacea, perché fornisce le informazioni esattamente nei punti dove servono ed evita un continuo “rimbalzare” dal codice alla carta.
In Visual Studio questo fatto assume un’importanza ancora maggiore: infatti esiste la possibilità di scrivere un tipo di commenti al codice (denominati “commenti XML”) che permettono di rendere visibili le informazioni anche per mezzo di IntelliSense, cioè quella tecnologia che permette di visualizzare delle informazioni man mano che scriviamo il codice, come nomi di namespace, di classi, di metodi, di attributi e di parametri, oltre che il loro uso. Vediamo come funziona.
Prendiamo ad esempio una semplice classe Class1 con un altrettanto semplice metodo test che accetta due parametri di tipo Integer. Il secondo parametro, inoltre, è un parametro opzionale con valore di default:
Public Class Class1
Public Function test(ByVal a As Integer,
Optional ByVal b As Integer = 2) As Integer
Return (a + b)
End Function
End Class
La funzione non fa altro che prendere i due argomenti e restituirne la somma. Il codice che utilizza questa classe è il seguente:
Public Class Form1
Private Sub Button1_Click(ByVal sender As System.Object,
ByVal e As System.EventArgs) _
Handles Button1.Click
Dim x As New Class1
MessageBox.Show(x.test(1, 2).ToString)
End Sub
End Class
Ovviamente si tratta di codice per gestire l’evento Click di un pulsante Button1, inserito in un form (Windows Forms).
Vediamo ora come si inserisce un commento alla Class1.
Per prima cosa commentiamo la Function test. E’ sufficiente posizionarci all’inizio della riga dove viene definita la Function e premere invio per creare uno spazio vuoto al di sopra della funzione. Poi ci spostiamo con il cursore nella riga vuota e digitiamo tre volte il carattere apice, ovvero ’’’.
A questo punto, apparirà automaticamente quanto segue:
''' <summary>
'''
''' </summary>
''' <param name="a"></param>
''' <param name="b"></param>
''' <returns></returns>
''' <remarks></remarks>
All’interno del blocco <summary> … </summary> possiamo quindi inserire un commento sulla funzione, per esempio “Funzione per sommare due numeri Integer”.
Vedete anche che sono stati inseriti i blocchi <param …> … </param> per inserire i commenti ai parametri da passare alla funzione. Inseriamo rispettivamente i commenti “Primo numero intero” e “Secondo numero intero”. I blocchi <param> … </param> compaiono automaticamente solo in presenza di parametri e solo in numero uguale al numero di parametri stessi.
Poi, ancora, abbiamo il blocco <returns> … </returns> per inserire il commento sul parametro restituito dalla funzione. Inseriamo “Restituisce un valore Integer con la somma dei due parametri passati alla funzione”.
Infine c’è un blocco <remarks> … </remarks> dove possiamo inserire informazioni note aggiuntive sull’utilizzo della funzione, per esempio “Somma due numeri Integer”.
La pagina di MSDN che elenca tutti questi tag XML e anche altri è la seguente:
http://msdn.microsoft.com/en-us/library/ms172653(VS.80).aspx
Ecco come diventano il nostro commento XML e la relativa funzione:
Public Class Class1
''' <summary>
''' Funzione per sommare due numeri Integer
''' </summary>
''' <param name="a">Primo numero intero</param>
''' <param name="b">Secondo numero intero</param>
''' <returns>
''' Restituisce un valore Integer con la somma dei
''' due parametri passati alla funzione
''' </returns>
''' <remarks>Somma due numeri Integer</remarks>
Public Function test(ByVal a As Integer,
Optional ByVal b As Integer = 2) As Integer
Return (a + b)
End Function
End Class
Allo stesso modo possiamo commentare la classe. Prima di tutto creiamo una riga vuota prima della riga di definizione della classe Class1, poi, come abbiamo fatto prima, digitiamo i tre caratteri apice. Il risultato è il seguente:
''' <summary>
'''
''' </summary>
''' <remarks></remarks>
Anche in questo caso possiamo inserire delle informazioni, questa volta per commentare la classe, per esempio così:
''' <summary>
''' Classe per effettuare operazioni numeriche
''' </summary>
''' <remarks>Contiene un test per la somma</remarks>
Ora vediamo cosa succede quando creiamo un oggetto derivato da tale classe e chiamiamo il metodo test.
Nel momento in cui selezioniamo Class1, IntelliSense ci mostra il commento a tale classe, così:
Allo stesso modo, scrivendo la chiamata al metodo test, otteniamo il seguente commento:
Infine, compilando i parametri da passare al metodo, vediamo questo commento:
… e questo:
L'Angolo di SuperMario 