Documentare il codice con commenti XML

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ì:

image

Allo stesso modo, scrivendo la chiamata al metodo test, otteniamo il seguente commento:

image

Infine, compilando i parametri da passare al metodo, vediamo questo commento:

image

… e questo:

image

About these ads

Pubblicato il 25 marzo 2010 su Novità. Aggiungi ai preferiti il collegamento . 3 commenti.

  1. Nota: funziona anche con Visual Basic 2008. Con C# funziona sostanzialmente allo stesso modo, tranne che i caratteri speciali da utilizzare non sono 3 apici ma tre slash (///).

  2. Grazie Mario del post, avevo cominciato con il tuo libro nel 2008, ti volevo chiedere se puoi consigliarmi un libro in inglese sul UML, so che ce ne sono tanti in giro e questo crea un po di confusione su dove appogiarsi per imparare UML, quantomeno attuale da usare con Visual basic, grazie ancora.

Rispondi

Inserisci i tuoi dati qui sotto o clicca su un'icona per effettuare l'accesso:

Logo WordPress.com

Stai commentando usando il tuo account WordPress.com. Chiudi sessione / Modifica )

Foto Twitter

Stai commentando usando il tuo account Twitter. Chiudi sessione / Modifica )

Foto di Facebook

Stai commentando usando il tuo account Facebook. Chiudi sessione / Modifica )

Google+ photo

Stai commentando usando il tuo account Google+. Chiudi sessione / Modifica )

Connessione a %s...

Iscriviti

Ricevi al tuo indirizzo email tutti i nuovi post del sito.

Unisciti agli altri 843 follower

%d blogger cliccano Mi Piace per questo: