Guida al Visual Basic .NET
Capitolo 111° - Documentare il sorgente
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:
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
C#, TypeScript, java, php, EcmaScript (JavaScript), Spring, Hibernate, React, SASS/LESS, jade, python, scikit, node.js, redux, postgres, keras, kubernetes, docker, hexo, etc...
|