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

10

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?
Steven Jeuris
quelle

Antworten:

3

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.

Arseni Mourzenko
quelle
1
Sie rufen eine Methode auf und möchten nicht wissen, was sie bewirkt!?
jk.
1
@jk: Er impliziert, dass er das schon vorher getan hat. Nur wenn es fehlschlägt, möchte er sich auf den Rückgabewert konzentrieren. +1 für den letzten Absatz, so fühle ich mich im Wesentlichen auch. Auch wenn die Dokumentation eine offensichtliche Tatsache wie in meinem Beispiel enthält, beruhigt sie den Leser von seinen Erwartungen. Wenn Kommentare richtig verwaltet werden, heißt es: "Diese Methode ist richtig durchdacht und macht nichts weiter als das, was hier erwähnt wird", wie in der msdn-Dokumentation.
Steven Jeuris
2

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

Links zu MSDN : <summary>.<returns>

Jake Berger
quelle
Danke für den Link. Aber nirgends beschreibt die msdn-Dokumentation des summaryStatus, was die Methode tut. Ich habe abgelehnt, bis Sie sich die Zeit genommen haben, Ihre Antwort zu aktualisieren, um den Unterschied zwischen den MSDN-Zuständen und den Formulierungen zu klären. ; p
Steven Jeuris
2
Ob MSDN etwas darüber sagt oder nicht, dies ist tatsächlich eine gute Richtlinie. In Ihrem Beispiel müssen Sie nicht die gesamte Zusammenfassung wiederholen. Sie können einfach sagen: "Gibt zurück, truewenn das Prädikat übereinstimmt." Wenn jemand wissen muss, was eine Übereinstimmung ausmacht, kann er den Rest der Dokumentation lesen.
Blrfl
@ Blrfl: Ich sage nicht, dass die Richtlinie falsch ist. Ich sage, es ist falsch, auf eine Quelle zu verweisen, was bedeutet, dass dort etwas geschrieben ist, wenn es nicht ist. Daher die Abwahl. Ich würde diese Antwort sehr gerne bearbeitet sehen.
Steven Jeuris
@StevenJeuris: Die Links zur MSDN-Dokumentation waren lediglich ergänzende Informationen. MSDN sagt NICHT "Wenn Sie ein <summary>und ein haben, <returns>tun Sie dies". Wie Blrfl sagte, ist dies nur eine Richtlinie, die man verwenden kann oder nicht.
Jake Berger
1
@StevenJeuris: Obwohl ich aufgrund der Art und Weise, wie es geschrieben wurde, sehen konnte, wie jemand darauf schließen kann, dass es von MSDN stammt.
Jake Berger
1

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.

Philip
quelle
1

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.
DXM
quelle
Ja, ich kann mich mit den genannten Punkten verbinden und ihnen mehr oder weniger folgen. Das Problem ist, dass dies eine ziemlich subjektive Konvention ist, was der Grund sein könnte, warum Microsoft sich dafür entschieden hat, returnsstattdessen immer etwas hinzuzufügen . Ich stelle auch fest, dass sie immer dieselbe Formulierung verwenden, z. B. "true if ...; andernfalls false. " Für boolesche Rückgabewerte. Ich frage mich, ob sie auch dafür eine Konvention festgelegt haben.
Steven Jeuris
0

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.

Caleb
quelle
Wenn ich es so schreibe, erkenne ich den Vorteil von Microsofts Standardmethode, mit "Bestimmt, ob ..." zu beginnen . Ich denke, es ist besser lesbar, da es zuerst erklärt, was es tut, bevor es sagt, was das Ergebnis davon ist. Das ist ein Schritt weniger Indirektion. Ich bin damit einverstanden, dass das returnsvon Microsoft viel zu lang ist. Wenn es etwas tun sollte, ist es einfach zu versichern, dass wahr bedeutet, dass es übereinstimmt, und falsch, dass es nicht übereinstimmt.
Steven Jeuris