Questo sito utilizza cookies, anche di terze parti, per mostrare pubblicità e servizi in linea con il tuo account. Leggi l'informativa sui cookies.
Username: Password: oppure
Guida al Visual Basic .NET - Documentare il sorgente

Guida al Visual Basic .NET

Capitolo 111° - Documentare il sorgente

<< Precedente Prossimo >>

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.

Tag di documentazione

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 

E viene visualizzato così:

VBNet_2_E1_8.jpg

<< Precedente Prossimo >>
A proposito dell'autore

Programmatore e analista .NET 2005/2008/2010 (in particolare C# e VB.NET), anche nell'implementazione Mono per Linux. Conoscenze approfondite di Pascal, PHP, XML, HTML 4.01/5, CSS 2.1/3, Javascript (e jQuery). Conoscenze buone di C, LUA, GML, Ruby, XNA, AJAX e Assembly 68000. Competenze basilari di C++, SQL, Hlsl, Java.