Was sollte ich in XML-Dokumentationskommentare aufnehmen?

Ich versuche, meinen Code besser zu dokumentieren, insbesondere wenn es um XML-Kommentare für Klassenmitglieder geht, aber oft fühlt es sich einfach albern an.

Im Fall von Ereignishandlern sind die Namenskonvention und die Parameter Standard und klar:

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

Ich habe auch häufig einfache Eigenschaften, die (IMO) eindeutig benannt sind, so dass die Zusammenfassung redundant ist:

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

Ich habe nicht das Gefühl, dass solche Kommentare keine Informationen hinzufügen, die die Erklärung selbst noch nicht enthält. Die allgemeine Weisheit scheint zu sein, dass ein Kommentar, der den Code wiederholt, am besten ungeschrieben bleibt.

Offensichtlich besteht XML-Dokumentation aus mehr als nur regulären Inline-Code-Kommentaren und wird im Idealfall zu 100% abgedeckt. Was soll ich in solchen Fällen schreiben? Wenn diese Beispiele in Ordnung sind, welchen Wert addieren sie, den ich jetzt vielleicht nicht schätze?

XML-Dokumentenkommentare sind für öffentliche Mitglieder bestimmt.

Die Compiler-Warnung besagt eindeutig Folgendes:

Fehlender XML-Kommentar für öffentlich sichtbaren Typ oder Member 'Type_or_Member'

Sie sollten privaten Mitgliedern nur XML-Kommentare hinzufügen, wenn diese Mitglieder nicht bereits anhand ihres Namens erkennbar sind.

Reine Meinung hier, also nimm es für das, was es wert ist.

Ich hasse überflüssige XML-Kommentare. Doppelt so für die Ghost-Doc-Stile, die dem Methoden- / Eigenschaftsnamen einfach Leerzeichen hinzufügen. Es fügt keinen Wert hinzu und wirft einfach meine Ansicht des tatsächlichen Codes durcheinander.

Wenn etwas geklärt werden muss, kommentieren Sie es auf jeden Fall. Mit kleinen fokussierten Methoden mit aussagekräftigen Namen kann jedoch viel Klarheit vermittelt werden. Kommentieren Sie Code nicht, wenn Sie ihn verbessern und den Kommentar überflüssig machen können.

Lassen Sie mich nicht einmal mit der unnötigen Verwendung von this.und beginnen Me..

Als Randnotiz hätte ich gerne ein Visual Studio-Addin, mit dem ich die Sichtbarkeit von XML-Kommentaren umschalten kann. (Hinweis Hinweis)

Auf einem öffentlichen Mitglied sollten XML-Dokumente ziemlich ausführlich und vollständig sein, wie @SLaks erwähnt hat.

Sie können jedoch auch für private, geschützte oder interne Mitglieder sehr nützlich sein, da Visual Studio Intellisense auffüllt und QuickInfos mit den XML-Dokumentkommentaren unterstützt.

Das bedeutet, dass:

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

Könnte vollkommen ausreichend sein, aber:

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

Es wird viel einfacher sein, sie an anderer Stelle in Ihrem Code schnell zu erkennen.

Im Allgemeinen schreibe ich in öffentlichen XML-Kommentaren für einige externe Benutzer der API und in internen XML-Kommentaren, die ich für mich oder andere in meinem Team schreibe.

Das Überspringen von Parameterbeschreibungen ist wahrscheinlich eine schlechte Idee für die ersteren und eine gute für die letzteren.

Ich würde (insbesondere in öffentlichen API-Dokumenten) immer hinzufügen, ob getoder setauf Eigenschaften:

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

Aus der Intellisense von C # ist nicht ersichtlich, ob es verfügbar ist getoder nicht. Wenn Sie setes jedoch in den XML-Kommentar einfügen , können Sie es anhand des Tooltips auf einen Blick erkennen.