it-swarm-eu.dev

Warum sind /// Kommentarblöcke wichtig?

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

Ich fing an, sie zu benutzen und stellte fest, dass sie mich ziemlich ärgerten, also hörte ich auf, sie zu benutzen, außer für Bibliotheken und statische Methoden. Sie sind sperrig und ich vergesse immer, sie zu aktualisieren.

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

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

49
Rachel

Verwenden Sie sie so oft wie möglich.

Ja, dies sind spezielle Kommentare, die zur Dokumentation der Methode werden. Die Inhalte von <summary>, die generierten Parameter-Tags usw. 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 versuchen, einfach die Methodensignatur zu lesen und auf das Beste zu hoffen).

91
Ryan Hayes

Ja, verwenden Sie sie unbedingt für alles, was Sie behalten möchten oder das Sie teilen möchten.

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

Als letztes habe ich die Dokumentation jeden Abend neu erstellt und als interne Homepage gehostet. Die Firmeninitialen waren MF, also MFDN;)

Normalerweise erstelle ich jedoch nur eine .chm-Datei, die leicht geteilt werden kann.

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

17
Tom Morgan

Wenn Ihr Codierungsstandard die Verwendung solcher Kommentare verlangt (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 in Betracht ziehen, solche Kommentare nicht zu verwenden. Sie können sie in den meisten Fällen vermeiden, indem Sie Ihren Code folgendermaßen ä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 ) {

    }
12
azheglov

Die Benennung Ihrer Klasse, Methode und Eigenschaft sollte selbstverständlich sein. Wenn Sie diese benötigen, ist dies 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 generieren sie die Dokumente, um jedem Entwickler bei der Verwendung zu helfen, und verhindern dies um sie zu schreiben.

Aber trotzdem schneiden Sie es, pflegen es oder löschen es.

4
John MacIntyre

Wenn Sie feststellen, dass Sie immer wieder zurückgehen und Ihre Kommentare bearbeiten müssen, um dem neuen Code zu entsprechen, machen Sie sie möglicherweise an erster Stelle falsch. Das Zusammenfassungselement sollte genau das enthalten - eine Zusammenfassung - das was und das warum der Sache, die Sie zusammenfassen.

Das Beschreiben von wie etwas, das in Kommentaren funktioniert, verstößt gegen DRY. Wenn Ihr Code nicht selbsterklärend genug ist, sollten Sie möglicherweise zurückgehen und den Refactor durchführen.

2
Nobody

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

Nein, ich habe nie von ihnen profitiert. [bei der Arbeit an vorhandenen Systemen, die gewartet werden mussten]

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

1
Preets

Das Vergessen, etwas zu tun, macht es nicht zu einer schlechten Idee. Vergessen, die Dokumentation zu aktualisieren ist. Ich fand diese sehr nützlich in meiner Programmierung 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 zu erstellen, das über die Funktionsweise des Codes hinausgeht. Wenn Sie etwas Nützliches durch Intelligenz auftauchen lassen können, werden die Leute Sie lieben.

1
Abe Miessler

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

Ich habe mit Kommentaren gespielt (///). Für eine Klasse können Sie einfach einen solchen Kommentar 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 weitere Informationen hinzufügen, indem Sie eine Beschreibung für Parameter und Rückgabetypen angeben.

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

1
Sreekumar P

Ich verwende das Äquivalent in VB (da ich nicht 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 ist vor dem Einfügen so gut wie abgeschlossen, um zu vermeiden, dass die Kommentare geändert werden müssen - oder dass sie "nicht synchron" sind.

Ich schreibe nicht unbedingt einen Roman - nur die Grundlagen, die Parameterbeschreibung und einige Bemerkungen (normalerweise, wenn dort etwas "Außergewöhnliches" vor sich geht - Problemumgehung oder anderer Mist, den ich lieber nicht drin hätte, sondern habe keine Wahl "für jetzt".) (Ja, ich weiß, dass "für jetzt" Jahre dauern kann.)

Ich bin stark 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).

0
MetalMikester

verwenden Sie sie 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 deren Projekt in Intellisense detaillierter dargestellt wird.

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

0
Richard

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 Personen, die neu im System sind, zur Verfügung gestellt werden können, damit sie beim Lernen etwas haben, auf das sie sich beziehen 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 fungieren. Wenn es muss irgendwo aufgeschrieben werden muss, dann ist es im Code der Ort, an dem es am wahrscheinlichsten auf dem neuesten Stand bleibt (wahrscheinlicher als ein herumschwebendes Word-Dokument).

0
Todd Williamson