Twitter Profile
salta alla navigazione

Visual Studio: documentare il proprio codice sorgente 26 Maggio 2010

Inviato da LukePet in : Chicche, Documenti, Guide, Informatica, Prodotti, Software, Sviluppo, Tecnologia, Tutorial, Windows , 1 commento finora

Ecco un altro post che attraversa il versante più “tecnico” dei contenuti di questo blog. Dopo averne già parlato poco tempo fa, torno ad affrontare l’argomento Visual Studio…e per la precisione: “Visual Studio & documentazione del codice”.

Qualche settimana fa mi sono deciso a produrre un po’ di documentazione tecnica in riferimento ad un progetto che sto portando avanti dove lavoro, così mi sono messo a ricercare una soluzione che mi soddisfacesse. Dopo qualche test sono riuscito a trovare una configurazione ideale per tenere allineata la documentazione del mio codice sorgente. Ora, visto che in rete (aldilà di qualche discussione) non ho trovato grossi tutorials a riguardo, riporto in questo post tutte le linee guida che ho seguito. Magari può tornare utile a qualcuno.

Punto 1° – Commentare sempre il codice!

Avere del codice ben commentato è fondamentale, se poi i commenti sono ben strutturati sarà possibile integrarli nella propria documentazione senza problemi. Insomma, abituatevi a fare una cosa come questa:
/// <summary>
/// This is MyFunction
/// </summary>
/// <param name="param1">First parameter</param>
/// <param name="param2">Second parameter</param>
/// <returns>My return value</returns>
public int MyFunction(string param1, double param2)
{
}

per avere un’idea più chiara dei tags che potete sfruttare nella scrittura dei vostri commenti buttate un occhio qua: Recommended Tags for Documentation Comments.

Punto 2° – Impostare le proprietà del progetto

Per ogni class library della vostra solution dovete abilitare la generazione del file XML di documentazione; per farlo andate nella finestra delle proprietà e spuntate la voce “XML documentation file”, come mostrato qui sotto: Continua a leggere…