Cosa devo includere nei commenti della documentazione XML?

Naviga le tue risposte
13

Sto cercando di documentare meglio il mio codice, soprattutto quando si tratta dei commenti XML sui membri della classe, ma spesso si tratta solo di uno stupido.

Nel caso di gestori di eventi, la convenzione di denominazione e i parametri sono standard e chiari: 

/// <summary>
/// Handler for myCollection's CollectionChanged Event.
/// </summary>
/// <param name="sender">Event Sender</param>
/// <param name="e">Event Arguments</param>
private void myCollection_CollectionChanged(object sender, NotifyCollectionChangedEventArgs e)
{
    // actual code here...
}

Ho spesso anche delle proprietà semplici che sono (IMO) chiamate chiaramente in modo che il sommario sia ridondante: 

/// <summary>
/// Indicates if an item is selected.
/// </summary>
public bool ItemIsSelected
{ get { return (SelectedItem != null); } }

Non credo che tali commenti non aggiungano alcuna informazione che la dichiarazione stessa non trasmette già. La saggezza generale sembra essere che un commento che ripete il codice è meglio lasciarlo non scritto.

Ovviamente, la documentazione XML non è solo un normale commento in codice, e idealmente avrà una copertura del 100%. Che dovrei scriverò in questi casi? Se questi esempi sono OK, quale valore aggiungono che forse non sto apprezzando adesso?

    
posta mbmcavoy 14.09.2011 - 00:24
fonte

3 risposte

9

I commenti del documento XML sono destinati ai membri pubblici.

L' avviso del compilatore indica chiaramente quanto segue:

Missing XML comment for publicly visible type or member 'Type_or_Member'

Dovresti aggiungere solo commenti XML ai membri privati se questi membri non sono già evidenti dal loro nome.

    
risposta data 14.09.2011 - 01:51
fonte
5

Pura opinione qui, quindi prendila per quello che vale.

I odio commenti xml superflui. Sinceramente così per quelli in stile ghost doc che aggiungono semplicemente spazi al nome metodo / proprietà. Non aggiunge valore e limita semplicemente la mia vista del codice attuale.

Se qualcosa ha bisogno di chiarimenti, a tutti i costi, commentalo. Tuttavia, un sacco di chiarezza può essere trasmessa da piccoli metodi focalizzati con nomi significativi. Non commentare il codice se puoi migliorarlo e rendere il commento non necessario.

Non iniziare nemmeno a utilizzare inutilmente this. e Me. .

Come nota a margine, mi piacerebbe avere un addin di Visual Studio che mi permetta di attivare la visibilità dei commenti xml. (suggerimento, suggerimento)

    
risposta data 14.09.2011 - 18:02
fonte
1

Su un membro pubblico, i documenti XML dovrebbero essere abbastanza dettagliati e completi, come menzionato da @SLaks.

Tuttavia possono essere davvero utili anche su membri privati, protetti o interni perché Visual Studio popolerà intellisense e aiuterà le descrizioni dei comandi con i commenti del documento XML.

Questo significa che: 

// describe what this does
private void DoSomething() 
{
    // or describe it here...

Potrebbe essere una documentazione perfettamente sufficiente, ma: 

/// <summary>describe what this does</summary>
private void DoSomething() 
{

Sarà molto più facile vedere rapidamente da altrove nel tuo codice.

Generalmente su commenti XML pubblici Sto scrivendo per un utente esterno dell'API e su commenti XML interni che sto scrivendo per me o per altri sul mio team.

Saltare le descrizioni dei parametri è probabilmente una cattiva idea per la prima e va bene per quest'ultima.

Vorrei aggiungere (soprattutto nei documenti API pubblici) includere sempre get o set nelle proprietà: 

/// <summary>Gets a value indicating whether an item is selected.</summary>
public bool ItemIsSelected
{ 
    get { return SelectedItem != null; } 
}

Non è ovvio per l'intellisense di C # se sono disponibili get o set , ma metterlo sul commento XML significherà che puoi dire a colpo d'occhio dal suggerimento.

    
risposta data 15.09.2011 - 09:44
fonte

Leggi altre domande sui tag

DDD, Saga ed event-sourcing: un'Azione compensativa può essere semplicemente un'eliminazione nell'archivio eventi? Programmazione del contratto - Deposito% e metodi di pagamento? Qualsiasi consiglio è apprezzato