Bene, ora che avete pensato, scritto e testato la vostra applicazione siete pronti per lanciarla sul mercato... o quasi. Nel caso il progetto
che avete completato sia pensato per poter essere utilizzato da altri programmatori, è bene (anzi, è necessario) documentare
il codice che avete scritto. In questa sezione ho introdotto i primi tools per il debugging, ivi compreso l'IntelliSense. Esso ci permette
di vedere la descrizione di ogni entità, e sarebbe veramente comodo se anche le nostre classi e i nostri metodi avessero una loro
descrizione. Per fare ciò, bisogna documentare il codice: in .NET, la documentazione si attua mediante un vero e proprio strumento
sintattico basato su XML. Per documentare una qualsiasi entità la si fa precedere da uno speciale attributo posto dopo tre apici.
Ecco una lista dei principali attributi/tag di documentazione:
- summary : una descrizione del membro e della sua funzione. Ad esempio:
''' <summary> ''' Descrizione del metodo ''' </summary> Sub DoSomething() '... End Sub
- example : un esempio di come utilizzare il membro in questione. Può contenere anche dei tag <code>, che visualizzano il testo compreso come un codice sorgente
- exception : contiene informazioni riguardo al verificarsi di un'eccezione e magari anche qualche consiglio su come risolvere l'errore.
Poiché le eccezioni variano, accetta un parametro di nome cref che espone il nome dell'eccezione. Ad esempio:
''' <exception cref="IndexOutOfRangeException"> ''' Si è specificato un valore di Iterazions ''' troppo elevato. ''' </exception> Public Sub TransformName(ByVal Name As String, ByVal Iterations As Byte) '... End Sub
Ovviamente, per il parametro cref, il compilatore offre l'aiuto dell'IntelliSense nel completamento automatico - param : descrive cosa debba essere passato come parametro. Dato che un metodo può avere più parametri, bisogna indicare
un parametro name per discernere gli argomenti. Riprendendo l'esempio di prima:
''' <param name="Name">Un nome qualsiasi, non nullo.</param> ''' <param name="Iterations">Il numero di volte che ''' la funzione di modifica viene applicata al nome.</param> Public Sub TransformName(ByVal Name As String, ByVal Iterations As Byte) End Sub
- typeparam : come param, ma usato per descrivere i parametri generics aperti:
''' <summary> ''' Fa qualcosa... ''' </summary> ''' <typeparam name="T">Un qualsiasi tipo reference.</typeparam> Sub DoSomething(Of T As Class)() End Sub
- remarks : altri dettagli utili sul membro
- returns : descrizione dell'oggetto restituito (funzioni/proprietà)
- value : descrizione dell'oggetto restituito (solo proprietà)
- see, seealso : indicano un riferimento ad un altra entità collegata logicamente a questa (un classico "vedi anche...")
Questo sorgente mostra l'uso dei tag di documentazione applicato ad ogni tipo di membro possibile:
''' <summary> ''' Rappresenta un esempio di tutti i tag di documentazione, ''' applicati ad ogni tipo di membro. ''' </summary> ''' <remarks>Servirà anche per mostrare le varie ''' icone nell'Object Browser</remarks> Public Class Documentazione ''' <summary> ''' Espone lo scheletro di una classe. ''' </summary> Friend Interface Interfaccia 'Lascio vuoto, poiché i membri di un'interfaccia 'sono pur sempre uguali a quelli di una classe, di 'cui sto scrivendo esempi. End Interface ''' <summary> ''' Espone alcune costanti numeriche sotto la forma di ''' identificatori che si ricordano più facilmente. ''' </summary> ''' <remarks>Anche i singoli valori possono avere ''' dei tag proprio come ogni altro membro.</remarks> Private Enum Enumeratore ''' <summary> ''' Il primo valore dell'enumeratore. Vale 1. ''' </summary> Primo = 1 ''' <summary> ''' Il secondo valore dell'enumeratore. Vale 2. ''' </summary> Secondo ''' <summary> ''' Il terzo valore dell'enumeratore. Vale 3. ''' </summary> Terzo End Enum ''' <summary> ''' Raggruppa al suo interno più valori di tipo base. ''' </summary> Friend Structure Struttura Dim A, B, C As Int16 End Structure ''' <summary> ''' Rappresenta un puntatore a metodo in modo sicuro. ''' </summary> ''' <param name="A">Un valore interno positivo, compreso tra 0 ''' e 255. Costituisce la trasparenza del messaggio.</param> ''' <param name="B">Un messaggio in forma di stringa.</param> Public Delegate Sub Delegato(ByVal A As Int16, ByVal B As String) ''' <summary> ''' Rappresenta un cambiamento di stato dell'oggetto. ''' </summary> Friend Event Evento As EventHandler ''' <summary> ''' Una qualsiasi data. ''' </summary> Friend Shared VariabileStatica As Date ''' <summary> ''' Rappresenta un valore booleano, vero o falso. ''' </summary> Public VariabileIstanza As Boolean ''' <summary> ''' Media l'interazione tra un campo privato e il programmatore. ''' </summary> ''' <value>Un valore che rappresenta VariabileIstanza.</value> ''' <returns>Restituisce un valore Booleano.</returns> Public Property Proprietà() As Boolean Get Return Me.VariabileIstanza End Get Set(ByVal Value As Boolean) Me.VariabileIstanza = Value End Set End Property ''' <summary> ''' Esegue un certo insieme di istruzioni. ''' </summary> ''' <param name="C">Il delegate da richiamare alla fine ''' del processo.</param> Public Sub Procedura(ByVal C As Delegato) End Sub ''' <summary> ''' Esegue un certo insieme di istruzioni, o manipola ''' un valore e quindi restituisce un risultato. ''' </summary> ''' <param name="I">Un numero intero qualsiasi.</param> ''' <returns>Restituisce l'antireciproco del numero dato.</returns> Public Function Funzione(ByVal I As Int16) As Single Return -(1 / I) End Function End Class ''' <summary> ''' Un semplice modulo, ossia una classe statica. ''' </summary> Module Modulo End Module