Que dois-je inclure dans les commentaires de documentation XML?

J'essaie de mettre un point d'honneur à mieux documenter mon code, en particulier en ce qui concerne les commentaires XML sur les membres de la classe, mais souvent cela semble juste idiot.

Dans le cas des gestionnaires d'événements, la convention de dénomination et les paramètres sont standard et clairs:

/// <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...
}

J'ai également fréquemment des propriétés simples qui sont (IMO) nommées clairement afin que le résumé soit redondant:

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

Je n'ai pas l'impression que de tels commentaires n'ajoutent aucune information que la déclaration elle-même ne transmet pas déjà. La sagesse générale semble être qu'il vaut mieux ne pas écrire un commentaire qui répète le code.

De toute évidence, la documentation XML est plus que de simples commentaires de code en ligne, et aura idéalement une couverture à 100%. Que dois- je écrire dans de tels cas? Si ces exemples sont OK, quelle valeur ajoutent-ils que je n'apprécie peut-être pas maintenant?

Les commentaires de doc XML sont destinés aux membres publics.

L' avertissement du compilateur indique clairement ceci:

Commentaire XML manquant pour le type ou le membre visible par le public 'Type_or_Member'

Vous ne devez ajouter des commentaires XML aux membres privés que si ces membres ne sont pas déjà évidents d'après leur nom.

L'opinion pure ici, alors prenez-la pour ce qu'elle vaut.

Je déteste les commentaires xml superflus. Doublement donc pour ceux de style doc fantôme qui ajoutent simplement des espaces au nom de la méthode / propriété. Il n'ajoute aucune valeur et encombre simplement ma vision du code réel.

Si quelque chose a besoin d'être clarifié, commentez-le. Cependant, beaucoup de clarté peut être transmise par de petites méthodes ciblées avec des noms significatifs. Ne commentez pas le code si vous pouvez l'améliorer et rendre le commentaire inutile.

Ne me lancez même pas sur l'utilisation inutile de this.et Me..

En guise de remarque, j'aimerais avoir un complément Visual Studio qui me permette de basculer la visibilité des commentaires xml. (indice, indice)

Sur un membre public, les documents XML doivent être assez verbeux et complets, comme l'a mentionné @SLaks.

Cependant, ils peuvent également être très utiles sur les membres privés, protégés ou internes, car Visual Studio remplira intellisense et aidera les info-bulles avec les commentaires de la documentation XML.

Cela signifie que:

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

Peut-être une documentation parfaitement suffisante, mais:

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

Sera beaucoup plus facile à voir rapidement ailleurs dans votre code.

Généralement sur les commentaires XML publics que j'écris pour certains utilisateurs externes de l'API, et sur les commentaires XML internes que j'écris pour moi ou d'autres membres de mon équipe.

Ignorer les descriptions des paramètres est probablement une mauvaise idée pour les premiers et bien pour les seconds.

J'ajouterais (dans les documents API publics en particulier) toujours inclure si getou setsur les propriétés:

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

Il n'est pas évident d'après l'intellisense de C # si getset sont disponibles ou , mais le mettre sur le commentaire XML signifie que vous pouvez le voir en un coup d'œil à partir de l'infobulle.