Ist das "Gets or Sets .." in der XML-Dokumentation von Eigenschaften erforderlich?

Ich suche eine Empfehlung für eine bewährte Methode für XML-Kommentare in C #. Wenn Sie eine Eigenschaft erstellen, hat die erwartete XML-Dokumentation anscheinend die folgende Form:

/// <summary>
/// Gets or sets the ID the uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID {
    get;
    set;
}

Da die Signatur der Eigenschaft jedoch bereits angibt, welche Operationen für die externen Clients der Klasse verfügbar sind (in diesem Fall sind es beides getund set), sind die Kommentare meiner Meinung nach zu gesprächig, und möglicherweise würde Folgendes ausreichen:

/// <summary>
/// ID that uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID {
    get;
    set;
}

Microsoft verwendet das erste Formular, sodass es sich anscheinend um eine implizite Konvention handelt. Aber ich denke, dass der zweite aus den von mir genannten Gründen besser ist.

Ich verstehe, dass diese Aussage geeignet ist, als nicht konstruktiv eingestuft zu werden, aber die Menge an Eigenschaften, die man kommentieren muss, ist riesig, und deshalb glaube ich, dass diese Frage das Recht hat, hier zu sein.

Ich werde alle Ideen oder Links zu offiziellen empfohlenen Praktiken zu schätzen wissen.

Die Signatur kann anderen Codeteilen mitteilen, welche Operationen verfügbar sind. Sie werden dem Codierer jedoch nicht eindeutig angezeigt, während er oder sie arbeitet, und die XML-Dokumentation ist für Benutzer gedacht und nicht für Compiler.

Nehmen Sie diese Klasse zum Beispiel:

public class MyClass
{
    /// <summary>
    /// The first one
    /// </summary>
    public int GetOrSet { get; set; }

    /// <summary>
    /// The second one
    /// </summary>
    public int GetOnly { get; private set; }

    /// <summary>
    /// The last one
    /// </summary>
    public int SetOnly { set; private get; }
}

Wenn Intellisense aufgerufen wird, um auf eine dieser Eigenschaften zuzugreifen, gibt es keine Angabe, in welche Eigenschaften geschrieben, von denen gelesen oder von beiden gelesen werden kann:

Auch beim Betrachten der Dokumentation sind wir uns nicht ganz sicher:

Als solche fügen wir die gets oder sets , gets oder sets hinzu , um dem Programmierer das Schreiben des Codes zu erleichtern. Es wäre sicherlich nicht das Schreiben eines großen Codeblocks, der einige Daten liest und verarbeitet, nur um festzustellen, dass Sie diese Daten nicht wie erwartet in die Eigenschaft zurückschreiben können.

StyleCop verwendet die Gets or Sets ...Notation, die es mit der Regel SA1623 erzwingt .

Die verlinkte Seite listet einen anderen Fall auf, den Sie nicht aufgelistet haben:

/// <summary>
/// Gets a value indicating whether the item is enabled.
/// </summary>
public bool Enabled
{
    get { return this.enabled; }
}

Die andere Option, die Sie auflisten, wäre.

/// <summary>
/// ID that uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID { get; set; }

vs

/// <summary>
/// ID that uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID { get; }

Was im Intellisense-Hinweis, dass die Eigenschaft schreibgeschützt ist, keine Informationen liefern würde, könnten Sie sich auch für diesen Fall eine Konvention einfallen lassen Gets ..., Gets or Sets...aber die Aufgabe ist gut, imo.

Es gibt auch andere in der StyleCop-Regel aufgelistete Varianten, die durch die Verwendung von, Gets or Sets...jedoch möglicherweise nicht ohne, deutlich werden.

Auch beim Generieren von Dokumentation aus Doxygen oder Sandcastle würde die vollständige Notation die API (zum Beispiel) besser dokumentieren.

Das einzige Mal, dass ich Informationen zum Abrufen und Festlegen einer Eigenschaft in den XML-Kommentaren hinzufüge, ist, wenn sie sich nicht wie erwartet verhält (direktes öffentliches Abrufen und Festlegen).

Wenn sie privat sind oder zusätzliche Logik enthalten, erwähne ich sie, ansonsten dokumentiere ich nur die Absicht der Eigenschaft.

Ich wäre glücklicher mit der ausführlicheren Version.

Der andere ist wie der Kommentar "Inkrementzähler", nachdem eine Zählervariable inkrementiert wurde.

Es ist offensichtlich, dass es ein Get and Set gibt. Wenn Sie einen privaten Setter hätten, wäre dies offensichtlich, da Sie das Schlüsselwort private hätten.

Kommentare sollten einen Mehrwert bieten und nicht nur eine Kommentarversion des eigentlichen Codes sein.