Sind XML-Kommentare erforderlich?

Früher war ich ein Fan davon, XML-Kommentare für die Dokumentation zu benötigen. Ich habe meine Meinung seitdem aus zwei Hauptgründen geändert:

1. Wie guter Code sollten Methoden selbsterklärend sein.
2. In der Praxis sind die meisten XML-Kommentare nutzloses Rauschen, das keinen zusätzlichen Wert bietet.

Oft verwenden wir einfach GhostDoc, um generische Kommentare zu generieren, und das meine ich mit nutzlosem Rauschen:

    /// <summary>
    /// Gets or sets the unit of measure.
    /// </summary>
    /// <value>
    /// The unit of measure.
    /// </value>
    public string UnitOfMeasure { get; set; }

Für mich ist das offensichtlich. Wenn jedoch spezielle Anweisungen enthalten sein sollten, sollten wir unbedingt XML-Kommentare verwenden.

Ich mag diesen Auszug aus diesem Artikel :

Manchmal müssen Sie Kommentare schreiben. Aber es sollte die Ausnahme sein, nicht die Regel. Kommentare sollten nur verwendet werden, wenn sie etwas ausdrücken, das nicht im Code ausgedrückt werden kann. Wenn Sie eleganten Code schreiben möchten, versuchen Sie, Kommentare zu entfernen, und schreiben Sie stattdessen selbstdokumentierenden Code.

Bin ich falsch zu glauben, wir sollten nur XML-Kommentare verwenden, wenn der Code nicht ausreicht, um sich selbst zu erklären?

Ich glaube, dies ist ein gutes Beispiel, bei dem XML-Kommentare hübschen Code hässlich aussehen lassen. Es braucht eine Klasse wie diese ...

public class RawMaterialLabel : EntityBase
{
    public long     Id                      { get; set; }
    public string   ManufacturerId          { get; set; }
    public string   PartNumber              { get; set; }
    public string   Quantity                { get; set; }
    public string   UnitOfMeasure           { get; set; }
    public string   LotNumber               { get; set; }
    public string   SublotNumber            { get; set; }
    public int      LabelSerialNumber       { get; set; }
    public string   PurchaseOrderNumber     { get; set; }
    public string   PurchaseOrderLineNumber { get; set; }
    public DateTime ManufacturingDate       { get; set; }
    public string   LastModifiedUser        { get; set; }
    public DateTime LastModifiedTime        { get; set; }
    public Binary   VersionNumber           { get; set; }

    public ICollection<LotEquipmentScan> LotEquipmentScans { get; private set; }
}

... und macht daraus:

/// <summary>
/// Container for properties of a raw material label
/// </summary>
public class RawMaterialLabel : EntityBase
{
    /// <summary>
    /// Gets or sets the id.
    /// </summary>
    /// <value>
    /// The id.
    /// </value>
    public long Id { get; set; }

    /// <summary>
    /// Gets or sets the manufacturer id.
    /// </summary>
    /// <value>
    /// The manufacturer id.
    /// </value>
    public string ManufacturerId { get; set; }

    /// <summary>
    /// Gets or sets the part number.
    /// </summary>
    /// <value>
    /// The part number.
    /// </value>
    public string PartNumber { get; set; }

    /// <summary>
    /// Gets or sets the quantity.
    /// </summary>
    /// <value>
    /// The quantity.
    /// </value>
    public string Quantity { get; set; }

    /// <summary>
    /// Gets or sets the unit of measure.
    /// </summary>
    /// <value>
    /// The unit of measure.
    /// </value>
    public string UnitOfMeasure { get; set; }

    /// <summary>
    /// Gets or sets the lot number.
    /// </summary>
    /// <value>
    /// The lot number.
    /// </value>
    public string LotNumber { get; set; }

    /// <summary>
    /// Gets or sets the sublot number.
    /// </summary>
    /// <value>
    /// The sublot number.
    /// </value>
    public string SublotNumber { get; set; }

    /// <summary>
    /// Gets or sets the label serial number.
    /// </summary>
    /// <value>
    /// The label serial number.
    /// </value>
    public int LabelSerialNumber { get; set; }

    /// <summary>
    /// Gets or sets the purchase order number.
    /// </summary>
    /// <value>
    /// The purchase order number.
    /// </value>
    public string PurchaseOrderNumber { get; set; }

    /// <summary>
    /// Gets or sets the purchase order line number.
    /// </summary>
    /// <value>
    /// The purchase order line number.
    /// </value>
    public string PurchaseOrderLineNumber { get; set; }

    /// <summary>
    /// Gets or sets the manufacturing date.
    /// </summary>
    /// <value>
    /// The manufacturing date.
    /// </value>
    public DateTime ManufacturingDate { get; set; }

    /// <summary>
    /// Gets or sets the last modified user.
    /// </summary>
    /// <value>
    /// The last modified user.
    /// </value>
    public string LastModifiedUser { get; set; }

    /// <summary>
    /// Gets or sets the last modified time.
    /// </summary>
    /// <value>
    /// The last modified time.
    /// </value>
    public DateTime LastModifiedTime { get; set; }

    /// <summary>
    /// Gets or sets the version number.
    /// </summary>
    /// <value>
    /// The version number.
    /// </value>
    public Binary VersionNumber { get; set; }

    /// <summary>
    /// Gets the lot equipment scans.
    /// </summary>
    /// <value>
    /// The lot equipment scans.
    /// </value>
    public ICollection<LotEquipmentScan> LotEquipmentScans { get; private set; }
}

Wenn Ihre Kommentare nur so aussehen:

/// <summary>
/// Gets or sets the sublot number.
/// </summary>
/// <value>
/// The sublot number.
/// </value>

Dann sind sie ja gar nicht so nützlich. Wenn sie so etwas lesen:

/// <summary>
/// Gets or sets the sublot number.
/// Note that the sublot number is only used by the legacy inventory system.
/// Latest version of the online inventory system does not use this, so you can leave it null. 
/// Some vendors require it but if you don't set it they'll send a request for it specifically.
/// </summary>
/// <value>
/// The sublot number.
/// </value>

Dann würde ich sagen, dass sie Wert haben. Um Ihre Frage zu beantworten: Kommentare sind erforderlich, wenn sie etwas sagen, was der Code nicht sagt.

Eine Ausnahme: Es ist gut, Kommentare zu öffentlich zugänglichen Elementen zu haben, wenn Sie eine Bibliothek / API schreiben, die der Öffentlichkeit zugänglich sein wird. Ich hasse es , eine Bibliothek zu benutzen und eine Funktion zu sehen, die getAPCDGFSocket()keine Erklärung dafür hat, was ein APCDGFSocket ist (ich würde mich über etwas so Einfaches wie freuen This gets the Async Process Coordinator Data Generator File Socket). In diesem Fall würde ich sagen, dass Sie ein Tool verwenden, um alle Kommentare zu generieren und dann diejenigen, die sie benötigen, manuell zu optimieren (und bitte stellen Sie sicher, dass Ihre kryptischen Akronyme erklärt werden).

Getter / Setter sind im Allgemeinen schlechte Beispiele für "Sind Kommentare notwendig?" weil sie normalerweise ziemlich offensichtlich sind und Kommentare nicht notwendig sind. Kommentare sind wichtiger für Funktionen, die einen Algorithmus ausführen, bei dem eine Erklärung, warum die Dinge so ausgeführt werden, wie sie sind, den Code viel verständlicher machen und auch zukünftigen Programmierern die Arbeit erleichtern könnte.

... und schließlich bin ich mir ziemlich sicher, dass diese Frage für alle Arten von Kommentaren relevant ist , nicht nur für diejenigen, die mit XML formatiert sind (die Sie verwenden, weil Sie in einer .NET-Umgebung arbeiten).

Die Kommentare, die für Benutzer, die den Code lesen können, nutzlos erscheinen, werden für Benutzer, die keinen Zugriff auf die Quelle haben, ziemlich nützlich. Dies geschieht, wenn die Klasse von Personen außerhalb Ihrer Organisation als externe API verwendet wird: Die aus Ihren XML-Dokumenten generierten HTMLs sind die einzige Möglichkeit, mehr über Ihre Klassen zu erfahren.

Ein Kommentar, der den Methodennamen mit zusätzlichen Leerzeichen zwischen den Wörtern wiederholt, bleibt jedoch nutzlos. Wenn Ihre Klasse außerhalb Ihrer Organisation verwendet werden soll, müssen Sie mindestens die gültigen Bereiche für Ihre Werte dokumentieren. Sie sollten beispielsweise sagen, dass die Einstellung UnitOfMeasureauf nullunzulässig ist, dass der dem Setter übermittelte Wert keine Leerzeichen am Anfang oder am Ende der Zeichenfolge usw. enthalten darf. Sie sollten auch den Bereich dokumentieren, in dem LabelSerialNumberer sich von dem einer Ebene unterscheidet Int32: Möglicherweise sind keine negativen Zahlen zulässig ^*oder erlaubt nicht mehr als sieben Ziffern. Ihre internen Benutzer halten dies möglicherweise für selbstverständlich, da sie Tag für Tag die Seriennummern überprüfen. Die externen Benutzer sind jedoch möglicherweise wirklich überrascht, eine Ausnahme von dem zu sehen, was wie ein unschuldiger Setter aussieht.

Sie haben absolut Recht, solche nutzlosen Kommentare zu vermeiden. Sie erschweren das Lesen des Codes, anstatt ihn zu vereinfachen, und beanspruchen zu viel Platz.

In meiner Praxis neigen Leute, die Kommentare mit Getter / Setter schreiben, dazu, Kommentare wegzulassen, wenn diese wirklich notwendig sind (wie das Erstellen einer 20-zeiligen SQL-Abfrage für eine Komponente ohne Dokumentation).

Ich schreibe Kommentare, wenn es andere offensichtliche Lösungen gibt. Ich gebe an, warum genau dieser Ansatz verwendet wurde. Oder wenn es schwierig ist, auf die Idee zu kommen, ohne alle Details zu kennen _ Ich liste kurz die Details auf, die zum Verständnis des Codes erforderlich sind.

Das Beispiel, das Sie mitbringen, besteht eher darin, Kommentare zu schreiben, um zu sagen, dass man Kommentare schreibt, als das Leben anderer (und auch ihrer) zu erleichtern.

Übrigens können Sie Ihre Fähigkeit, Kommentare zu schreiben, verbessern, indem Sie zu Ihrem alten Code zurückkehren und versuchen, ihn zu verstehen (möglicherweise erkennen Sie Ihren eigenen Code in 2-3 Monaten sogar nicht - es ist absolut so, als würden Sie den Code eines anderen lesen). Wenn Sie dies schmerzlos tun, ist alles in Ordnung.