Sollte ein Methodenkommentar sowohl eine Zusammenfassung als auch eine Rückgabebeschreibung enthalten, wenn sie oft so ähnlich sind?

Ich bin ein Befürworter von ordnungsgemäß dokumentiertem Code und bin mir der möglichen Nachteile bewusst . Das liegt außerhalb des Rahmens dieser Frage.

Ich befolge gerne die Regel, XML-Kommentare für jedes öffentliche Mitglied hinzuzufügen , wenn man bedenkt, wie sehr ich IntelliSense in Visual Studio mag.

Es gibt jedoch eine Form der Redundanz, die selbst einen übermäßigen Kommentator wie mich stört. Nehmen Sie als Beispiel List.Exists () .

/// <summary>
///     Determines whether the List<T> contains elements
///     that match the conditions defined by the specified predicate.
/// </summary>
/// <returns>
///     true if the List<T> contains one or more elements that match the
///     conditions defined by the specified predicate; otherwise, false.
/// </returns>
public bool Exists( Predicate<T> match )
{
    ...
}

Summaryund returnssagen im Grunde das Gleiche. Am Ende schreibe ich die Zusammenfassung oft eher aus einer returnsPerspektive und lasse die returnsDokumentation ganz fallen.

Gibt true zurück, wenn die Liste Elemente enthält, die den durch das angegebene Prädikat definierten Bedingungen entsprechen, andernfalls false.

Außerdem wird die Rückgabedokumentation nicht in IntelliSense angezeigt, daher schreibe ich lieber sofort relevante Informationen in summary.

1. Warum sollten Sie jemals returnsgetrennt von dokumentieren müssen summary?
2. Gibt es Informationen darüber, warum Microsoft diesen Standard übernommen hat?

Sie können voneinander schließen, aber diese beiden Abschnitte bleiben getrennt, da es hilfreich ist, sich bei der Überprüfung / Verwendung des Codes auf den zu konzentrieren, der die Person interessiert .

Anhand Ihres Beispiels würde ich lieber schreiben:

/// <summary>
/// Determines whether the List<T> contains elements that match the conditions
/// defined by the specified predicate.
/// </summary>
/// <returns>
/// A value indicating whether at least one element matched the predicate.
/// </returns>
public bool Exists(Predicate<T> match)
{
    ...
}

• Wenn ich diesen Code überprüfe und wissen möchte, was die Methode bewirkt, lese ich die Zusammenfassung und das ist alles, was mich interessiert.

• Stellen wir uns nun vor, ich verwende Ihre Methode und der Rückgabewert, den ich erhalte, ist angesichts der Eingabe seltsam. Jetzt möchte ich nicht wirklich wissen, was die Methode tut, aber ich möchte etwas mehr über den Rückgabewert wissen. Hier <returns/>hilft der Abschnitt, und ich muss die Zusammenfassung nicht lesen.

Auch in diesem Beispiel können Sie die Zusammenfassung aus <returns/>und den erwarteten Rückgabewert aus der Zusammenfassung ableiten. Aber das gleiche Argument an die Spitze zu treiben , gibt es keine Notwendigkeit , Ihre Methode überhaupt zu dokumentieren in diesem Fall: der Name der Methode, nach innen setzen List<T>, mit Predicate<T> matchals ein einziges Argument ist sich ganz explizit.

Denken Sie daran, dass der Quellcode einmal geschrieben, aber häufig gelesen wurde . Wenn Sie die Verbrauchsteuer für die weiteren Leser Ihres Codes reduzieren können, während Sie zehn Sekunden damit verbringen, einen zusätzlichen Satz in die XML-Dokumentation zu schreiben, tun Sie dies.

Meine Verwendung:
<summary>beschreibt, was die Methode tut (um die zu bekommen <returns>).
<returns>beschreibt den Rückgabewert .

Links zu MSDN : <summary>.<returns>

Warum sollten Sie Rücksendungen jemals getrennt von der Zusammenfassung dokumentieren müssen?

Ich denke, wenn der zusammenfassende Teil wirklich lang und beschreibend ist, kann es nützlich sein, am Ende einen separaten, kurzen Rückgabeteil zu haben.

Normalerweise schreibe ich nur den <summary>Teil in meinen eigenen Code und formuliere ihn so, wie Sie "Returns _ " gesagt haben .

Ich habe alle Bemerkungen eingefügt, die ein Aufrufer wissen sollte, die aus dem Methodennamen und den Parametern (und ihren Namen) nicht ersichtlich sind. Hoffentlich machen der Methodenname und die Parameter deutlich genug, dass der Kommentar sehr kurz sein kann.

Ich bin in letzter Zeit von derselben philosophischen Frage zerrissen worden und bin mir immer noch nicht sicher, was eine gute Lösung ist. Aber bisher war dies mein Ansatz ...

• Die Methodendokumentation beschreibt nur, was externe Anrufer wissen müssen. Es wird nicht darüber gesprochen, wie diese Arbeit intern ausgeführt wird, sondern es wird erwähnt, a) warum der Aufrufer diese Methode aufrufen möchte, b) was die erwarteten Ergebnisse des Aufrufs der Methode wären. Wenn dokumentiert werden muss, wie die Methode funktioniert, füge ich das in den Code-Body selbst ein.
• Wenn eine Methode ausreichend komplex ist, scheinen eine allgemeine Beschreibung und ein separater Abschnitt [Rückgabe] gerechtfertigt zu sein. Sie möchten nicht, dass der Leser die gesamte Beschreibung liest und versucht, daraus zu schließen, wie der Rückgabewert zu interpretieren ist.
• Wenn die Methode so einfach ist, dass der beste Weg, um zu beschreiben, was sie tut, darin besteht, etwas wie "Diese Methode gibt die Adresse einer Person zurück" zu sagen, überspringe ich den Abschnitt [Rückgabe], da das Hinzufügen gegen das DRY-Prinzip zu verstoßen scheint und ich bin ein großer Befürworter davon. Viele Einzeiler-Zugriffsmethoden scheinen in diese Kategorie zu fallen.

Die Zusammenfassung sollte so beschreibend sein, wie es nützlich sein könnte. Die Beschreibungen der Parameter und des Rückgabewerts sollten kurz und bündig sein. Wenn Sie zwischen einem Wort und fünf wählen können, verwenden Sie eins. Lassen Sie uns Ihr Beispiel verschärfen:

true, wenn die Liste ein oder mehrere Elemente enthält, die den durch das angegebene Prädikat definierten Bedingungen entsprechen; sonst falsch.

wird

true, wenn ein Element der Liste mit dem Prädikat übereinstimmt; sonst falsch.