Warum sind /// Kommentarblöcke wichtig?

49

Jemand hat einmal gesagt, wir sollten allen unseren Methoden die /// <summary>Kommentarblöcke (C #) voranstellen , haben aber nicht erklärt, warum.

Ich habe angefangen, sie zu verwenden, und festgestellt, dass sie mich ziemlich geärgert haben. Daher habe ich sie mit Ausnahme von Bibliotheken und statischen Methoden nicht mehr verwendet. Sie sind sperrig und ich vergesse immer, sie zu aktualisieren.

Gibt es einen guten Grund, /// <summary>in Ihrem Code Kommentarblöcke zu verwenden ?

Normalerweise benutze ich die //ganze Zeit Kommentare, es sind nur die /// <summary>Blöcke, über die ich mich gewundert habe.

Rachel
quelle
1
Ich war mir nicht sicher, ob diese Kommentarblöcke persönliche Vorlieben oder empfohlene Standards waren
Rachel
1
Ich denke auch so.
Ryan Hayes
30
Ich denke, das ist genau die Art von Frage, die hierher gehört. Es besteht eine gute Chance, dass dies beim Stackoverflow als subjektiv abgeschlossen wird.
Paddyslacker
Verwenden Sie <summary> -Blöcke, wenn Sie Dokumentation generieren möchten. Dies ist sinnvoll, wenn Sie eine API erstellen, die andere Benutzer verwenden können. Dies für jede Methode zu tun, ist übertrieben und verringert Ihre Flexibilität.
Macneil

Antworten:

91

Benutze sie so oft wie möglich.

Ja, das sind spezielle Kommentare, die zur Dokumentation der Methode werden. Der Inhalt von <summary>, die Parameter-Tags usw., die generiert werden, werden in Intellisense angezeigt, wenn Sie oder eine andere Person bereit sind, Ihre Methode aufzurufen. Sie können im Wesentlichen die gesamte Dokumentation für Ihre Methode oder Klasse anzeigen, ohne in die Datei selbst gehen zu müssen, um herauszufinden, was sie tut (oder einfach die Methodensignatur lesen und auf das Beste hoffen zu müssen).

Ryan Hayes
quelle
22
+1 Verwenden Sie sie unbedingt. Sie werden überrascht sein, wie nützlich es ist, sie zu haben, wenn Sie Ihre Komponenten jemals wiederverwenden und all diese großartigen Dokumentationen in Intellisense zur Verfügung haben.
Walter
4
Auch wenn Sie Visual Studio verwenden und eine Zeile mit /// unmittelbar vor einer Klassen-, Methoden- oder Felddeklaration beginnen, generiert VS die XML-Dokumentationsstruktur für Sie - Sie müssen sie nur ausfüllen. Ich bin damit einverstanden, dass sie in Anspruch genommen wird viel Platz auf Ihrem Bildschirm, aber es ist ein würdiger Kompromiss, würde ich sagen. Außerdem bietet F # eine bessere Unterstützung (z. B. müssen Sie <summary> und </ summary> nicht verwenden, da diese als "angenommen" gelten).
ShdNx
7
Da diese Antwort bereits die beste Wahl ist, möchte ich nur meinen Kommentar hinzufügen: Als ich herausfand, dass die Zusammenfassung für Intellisense verwendet wird und meine Projekte auf ihre aktuelle Größe angewachsen sind, war ich sehr froh, diese Funktion gefunden zu haben. Das Erinnern daran, wofür meine Methoden und Klassen bestimmt sind, wurde zu einer großen Herausforderung, und die Dokumentation von Code über diesen Mechanismus vereinfachte die Dinge erheblich. So konnte ich mich auf neuen Code und Wiederverwendbarkeit konzentrieren, anstatt mich daran zu erinnern, was vor Monaten getan wurde.
JYelton
3
Nur eine Sache zum Hinzufügen, diese Kommentare werden nicht in die DLL kompiliert, Sie müssen die zugehörige XML-Datei mit Ihrer DLL liefern.
Benjol
Sie sind nützlich, aber sie machen die aktuelle Klasse sehr unlesbar. Ich wünschte, es gäbe einen anderen Weg, der den Code nicht überfrachtet.
Jeroen van Langen
16

Ja, verwenden Sie sie auf jeden Fall für alles, was Sie behalten möchten oder teilen möchten.

Verwenden Sie sie auch in Verbindung mit Sandcastle und dem Sandcastle Help File Builder , der die XML-Ausgabe in eine ansprechende Dokumentation im MSDN-Stil umwandelt.

Als letztes haben wir die Dokumentation jeden Abend neu erstellt und als interne Homepage gehostet. Die Firmeninitialen waren MF, also war es MFDN;)

Normalerweise erstelle ich nur eine .chm-Datei, die sich leicht austauschen lässt.

Sie wären überrascht, wie süchtig Sie danach sind, alles zu dokumentieren, sobald Sie es im MSDN-Format sehen!

Tom Morgan
quelle
1
Der Link zum Blog scheint tot zu sein (letzter Beitrag vor 5 Jahren mit kaputtem HTML auf der ganzen Seite), und der Ort des Projekts ist umgezogen. Haben Sie einen aktualisierten Link für Sandcastle?
12

Wenn Ihr Codierungsstandard verlangt, dass Sie solche Kommentare verwenden (und ein Codierungsstandard für eine API oder ein Framework dies möglicherweise verlangt), haben Sie keine andere Wahl, als solche Kommentare zu verwenden.

Andernfalls sollten Sie ernsthaft erwägen, solche Kommentare nicht zu verwenden. Sie können sie in den meisten Fällen vermeiden, indem Sie Ihren Code wie folgt ändern:

    /// <summary>
    /// Checks if a user is authorized to access the resource
    /// </summary>
    public bool SecurityCheck( User user ) {

    }

zu

    /// <summary>
    /// Checks if a user is authorized to access the resource
    /// </summary>
    public bool IsAuthorizedToAccessResource( User user ) {

    }

zu

    public bool IsAuthorizedToAccessResource( User user ) {

    }
Azheglov
quelle
11
Ich bin damit einverstanden, dass Code so oft wie möglich selbstdokumentierend ist. Ich empfehle jedoch, diese Art von Kommentaren zu verwenden, wann immer dies möglich ist (und häufiger als generische // Kommentare). Die /// XML-Kommentare sind für die Verwendung mit IntelliSense konzipiert. Dies kann die Entwicklung in den nächsten Monaten erleichtern, wenn Sie versuchen, eine von Ihnen erstellte Bibliothek zu implementieren, und sich nicht mehr genau erinnern, wie sie funktioniert.
Matt DiTrolio
2
Und ich denke, nicht nur aus der Sicht von Intellisense, sondern auch aus der Sicht der automatischen Dokumentationserstellung sind XML-Kommentare nützlich. Wie bei allen Kommentaren macht dies jedoch nur Sinn, wenn die Kommentare selbst nützlich sind und den selbst dokumentierten Code ergänzen.
Vaibhav
5
Ich stimme zu, dass der Codierungsstandard beim Schreiben öffentlicher Klassen einer API oder eines Frameworks das Einfügen von Kommentaren in den Code verlangen sollte, damit IntelliSense- und Dokumentations-Tools verwendet werden können. Aber das ist noch nicht alles. Abgesehen von dieser Sorge ist der Ansatz, den ich hier befürworte, wenn Sie versuchen, Ihren Code sauberer und klarer zu machen, sich auf den Code selbst zu konzentrieren, nicht auf den Kommentar, der den Code beschreibt.
Azheglov
3
@JYelton: Dein Kommentar entspricht nicht meiner Antwort. Ich implizierte aussagekräftigere, aber nicht unbedingt ausführlichere Namen, sicherlich keine 60-stellige Kennung für eine häufig aufgerufene öffentliche Funktion. Sie haben auch eine scheinbar hoch spezialisierte Funktion, die jedoch einen sehr allgemeinen Datentyp (XmlDocument) hat - das ist ein Codegeruch. Ihr 60-stelliger Bezeichner beschreibt dann "wie" und nicht "was" - einer öffentlichen Methode. Das ist ein anderer Geruch. Die Hauptbotschaft lautet: Denken Sie zuerst an den Code, nicht an den Kommentar.
Azheglov
2
@JYelton Das Problem mit Ihrem Methodennamen ist nicht, dass er beschreibend ist, sondern dass er mindestens zwei separate Operationen beschreibt und daher in mindestens zwei unabhängige Methoden umgestaltet werden sollte.
Neal
4

Die Benennung Ihrer Klasse, Methode und Eigenschaft sollte selbstverständlich sein. Wenn Sie diese also benötigen, ist es wahrscheinlich ein Geruch.

Ich würde jedoch empfehlen, sie für alle öffentlichen Klassen, Methoden und Eigenschaften in einer API, Bibliothek usw. zu verwenden. Zumindest werden sie die Dokumente generieren, die jedem Entwickler helfen, der sie verwendet, und Sie daran hindern, sie zu verwenden um sie zu schreiben.

Aber wie auch immer Sie es schneiden, pflegen oder löschen.

John MacIntyre
quelle
11
Das Benennen ist eine Sache, aber das Auflisten von Einschränkungen für Parameter oder potenziell ausgelöste Ausnahmen ist immer noch wertvoll.
Adam Lear
Ja, ich gebe zu, Sie haben einen Punkt, aber die meiste Zeit sind die Parameterbeschränkungen offensichtlich, nicht wahr?
John MacIntyre
Ich bin nicht sicher, ob ich John zustimme. Mit dieser Logik sollte keine der .NET Framework-Methoden eine Intellisense-Hilfe erhalten.
Vaibhav
1
@vaibhav - Ich habe gesagt "Ich würde empfehlen, sie für öffentliche Klassen, Methoden und Eigenschaften in einer API, Bibliothek usw. zu verwenden."
John MacIntyre
1
@ John - seltsam, ich hätte schwören können, dass ich etwas ganz anderes gelesen habe, als ich diesen Kommentar schrieb. Weil dein zweiter Absatz genau das ist, was ich an anderer Stelle in diesem Thread gesagt habe. Also muss ich Steine ​​im Kopf haben, um diesen Kommentar zu schreiben. Ja, dem stimme ich zu.
Vaibhav
2

Wenn Sie feststellen, dass Sie Ihre Kommentare immer wieder bearbeiten müssen, um sie mit neuem Code abzustimmen, könnten Sie sie an erster Stelle falsch machen. Das Zusammenfassungselement sollte genau das enthalten - eine Zusammenfassung - das Was und Warum der Sache, die Sie zusammenfassen.

Das Beschreiben, wie etwas in Kommentaren funktioniert, verstößt gegen DRY. Wenn Ihr Code nicht selbsterklärend genug ist, sollten Sie vielleicht zurückgehen und überarbeiten.

Niemand
quelle
1

Ja, ich habe sie geschaffen. [beim Erstellen neuer Systeme von Grund auf]

Nein, ich habe noch nie von ihnen profitiert. [wenn an bestehenden Systemen gearbeitet wird, die gewartet werden müssen]

Ich habe festgestellt, dass "Zusammenfassungs" -Kommentare möglicherweise nicht mehr mit dem Code synchronisiert sind. Und wenn ich ein paar schlechte Kommentare bemerke, neige ich dazu, das Vertrauen in alle Kommentare zu diesem Projekt zu verlieren - Sie sind sich nie sicher, welchen Sie vertrauen sollen.

Preets
quelle
Veraltete Kommentare können jedoch als Codegeruch betrachtet werden, insbesondere auf der Zusammenfassungsebene. Wenn andere Entwickler Funktionen ändern und die Zusammenfassung ihrer Aktivitäten nicht aktualisieren, kann man argumentieren, dass sie ihre Arbeit nicht korrekt dokumentieren.
rjzii
1

Etwas zu vergessen macht es nicht zu einer schlechten Idee. Das Vergessen, jegliche Dokumentation zu aktualisieren, ist. Ich habe diese in meiner Programmierung sehr nützlich gefunden und Leute, die meinen Code erben, sind dankbar, sie zu haben.

Dies ist eine der sichtbarsten Möglichkeiten, Ihren Code zu dokumentieren.

Es ist mühsam, den Quellcode zu finden, um die Inline-Dokumentation zu lesen oder ein Dokument auszulesen, das die Funktionsweise des Codes überprüft. Wenn Sie etwas Nützliches durch Intelligenz auftauchen lassen können, werden Sie die Leute lieben.

Abe Miessler
quelle
1

" Es muss sehr viel benutzt werden, wie ich;) "

Früher habe ich mit Kommentaren (///) gespielt. Für eine Klasse können Sie einfach einen Kommentar wie diesen abgeben

namespace test
{
    /// <summary>
    /// Summary description for Calendar.
    /// </summary>
    public partial class DatePicker : System.Web.UI.Page
    {

Für eine Methode können Sie jedoch eine Beschreibung für Parameter und Rückgabetypen hinzufügen.

/// <summary>
/// Assign selected cases to the participating users based on the filters and configurations
/// </summary>
/// <param name="noOfParticipants">No. of participants to the Table</param>
/// <param name="value">Value of the participant</param>
/// <returns>No Of Cases Assigned on successfull completion</returns>
public long AssignCasesToParticipatingUsers(int noOfParticipants,string value)
{

Sie können eine Verknüpfung zum Erstellen dieses Kommentars verwenden (///+Tab).

Sreekumar P
quelle
0

mit Ausnahme von Bibliotheken

Das ist die Zeit, in der sie nützlich sind. Wenn die Generierung der XML-Dokumentation aktiviert ist und ein Verweis auf die Assembly ohne ihr Projekt in Intellisense detaillierter angezeigt wird.

Aber für die Interna des aktuellen Projekts stehen sie nur im Weg.

Richard
quelle
0

Ich benutze sie, aber wie einige andere Leute nicht allgemein gesagt haben. Bei kleinen Methoden können sie leicht größer sein als der Code, den sie erklären. Sie sind am nützlichsten, um Dokumentationen zu erstellen, die neuen Benutzern des Systems zur Verfügung gestellt werden können, damit sie beim Lernen auf etwas verweisen können. Obwohl wir als Programmierer normalerweise herausfinden können, was ein Code ist, ist es schön, die Kommentare zu haben, die uns führen und als Krücke dienen. Wenn es hat irgendwo abgeschrieben wird dann im Code ist der Ort , es ist sehr wahrscheinlich , aktualisiert zu bleiben (wahrscheinlicher ist als ein Word - Dokument im Umlauf).

Todd Williamson
quelle
0

Ich verwende das Äquivalent in VB (da ich kein C # verwenden darf - anscheinend ist es zu schwer ... kein Kommentar.) Ich finde sie sehr praktisch. Die meiste Zeit warte ich, bis der Vorgang oder die Funktion so gut wie abgeschlossen ist, bevor ich sie eingebe, um zu vermeiden, dass die Kommentare geändert werden müssen - oder sie "nicht synchron" sind.

Ich schreibe nicht unbedingt einen Roman - nur die Grundlagen, die Parameterbeschreibung und einige Bemerkungen (normalerweise, wenn etwas "Außergewöhnliches" vor sich geht - Workaround oder andere Scheiße, die ich lieber nicht drin habe, sondern habe) Keine Wahl "für jetzt".) (Ja, ich weiß, dass "für jetzt" Jahre dauern kann.)

Ich bin sehr irritiert von unkommentiertem Code. Ein Berater hat die erste Version einer unserer Komponenten geschrieben und nichts kommentiert und seine Namenswahl lässt hier und da zu wünschen übrig. Er ist seit über einem Jahr weg und wir sortieren immer noch seine Sachen (zusätzlich zur Arbeit an unseren eigenen Sachen).

MetalMikester
quelle