Warum sind /// Kommentarblöcke wichtig?

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.

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

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!

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 ) {

    }

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.

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.

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.

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.

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

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.

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

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