Cosa devo includere nei commenti sulla documentazione XML?

Sto cercando di documentare meglio il mio codice, soprattutto quando si tratta dei commenti XML sui membri della classe, ma spesso mi sembra sciocco.

Nel caso dei 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...
}

Inoltre ho spesso proprietà semplici che sono (IMO) chiaramente definite in modo che il riepilogo sia ridondante:

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

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

Ovviamente, la documentazione XML è più di semplici commenti di codice in linea e idealmente avrà una copertura del 100%. Cosa dovrei scrivere in questi casi? Se questi esempi sono OK, quale valore aggiungono che potrei non apprezzare ora?

I commenti sui documenti XML sono destinati ai membri pubblici.

L' avviso del compilatore afferma chiaramente questo:

Commento XML mancante per tipo o membro visibile pubblicamente "Type_or_Member"

Dovresti aggiungere commenti XML ai membri privati ​​solo se tali membri non sono già evidenti dai loro nomi.

Pura opinione qui, quindi prendilo per quello che vale.

Io odio commenti XML superflui. Doppiamente per quelli in stile fantasma doc che aggiungono semplicemente spazi al nome metodo / proprietà. Non aggiunge alcun valore e confonde semplicemente la mia visione del codice reale.

Se qualcosa ha bisogno di chiarimenti, commentalo sicuramente. Tuttavia, molta chiarezza può essere trasmessa da piccoli metodi focalizzati con nomi significativi. Non commentare il codice se è possibile migliorarlo e rendere il commento non necessario.

Non farmi nemmeno iniziare sull'uso non necessario di this.e Me..

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

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

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

Ciò 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 altre parti del codice.

Generalmente su commenti XML pubblici sto scrivendo per alcuni utenti esterni dell'API e su commenti XML interni sto scrivendo per me o altri nel mio team.

Saltare le descrizioni dei parametri è probabilmente una cattiva idea per il primo e va bene per il secondo.

Vorrei aggiungere (in particolare nei documenti API pubblici) includere sempre se geto setsulle proprietà:

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

Dall'intellisense di C # non è ovvio se geto setsiano disponibili, ma inserendolo nel commento XML significherà che puoi capire a colpo d'occhio dalla descrizione dei comandi.