Czy „Pobiera lub ustawia…” jest konieczne w dokumentacji XML właściwości?

Szukam zalecenia najlepszych praktyk dla komentarzy XML w języku C #. Podczas tworzenia właściwości wygląda na to, że oczekiwana dokumentacja XML ma następującą postać:

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

Ale ponieważ podpis właściwości już mówi ci, jakie operacje są dostępne dla zewnętrznych klientów klasy (w tym przypadku jest to jedno geti drugie set), wydaje mi się, że komentarze są zbyt gadatliwe i być może wystarczą następujące informacje:

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

Microsoft używa pierwszej formy, więc wygląda na to, że jest to dorozumiana konwencja. Ale myślę, że drugi jest lepszy z powodów, które podałem.

Rozumiem, że to pytanie jest adeptem do bycia oznaczonym jako niekonstruktywne, ale liczba właściwości, które należy skomentować, jest ogromna, więc uważam, że to pytanie ma prawo tu być.

Będę wdzięczny za wszelkie pomysły lub linki do oficjalnie zalecanych praktyk.

Podpis może informować inne fragmenty kodu, jakie operacje są dostępne; nie są one jednak wyraźnie widoczne koderowi, ponieważ on lub ona pracuje, a dokumentacja XML jest przeznaczona dla użytkowników, a nie kompilatora.

Weźmy na przykład tę klasę:

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; }
}

Kiedy inteligencja jest pobierana w celu uzyskania dostępu do jednej z tych właściwości, nie ma wskazania, do których można zapisać, odczytać lub oba:

Podobnie przeglądając dokumentację, nie jesteśmy również do końca pewni:

W związku z tym dodajemy pakiety lub zestawy , pliki lub zestawy, aby ułatwić programistom pisanie kodu. Z pewnością nie byłoby napisać dużego bloku kodu, który odczytuje i przetwarza niektóre dane tylko po to, aby dowiedzieć się, że nie można zapisać tych danych z powrotem do właściwości zgodnie z oczekiwaniami.

StyleCop używa Gets or Sets ...notacji, którą wymusza zgodnie z regułą SA1623 .

Na połączonej stronie wymieniono inny przypadek, którego nie wymieniono:

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

Inną opcją, którą wymieniasz, będzie.

/// <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; }

Które nie dostarczają informacji o podpowiedź Intellisense, że właściwość jest tylko do odczytu, można wymyślić konwencji o tym przypadku, ale Gets ..., Gets or Sets...spełnia swoje zadanie ładnie imo.

Istnieją również inne warianty wymienione w regule StyleCop, które są przejrzyste przy użyciu, Gets or Sets...ale mogą nie być bez.

Również przy generowaniu dokumentacji z czegoś takiego jak Doxygen lub Sandcastle pełna notacja lepiej udokumentuje API (na przykład).

Jedynie raz dodam informacje o pobieraniu i ustawianiu właściwości w komentarzach XML, kiedy nie zachowuje się ona zgodnie z oczekiwaniami (proste publiczne pobranie i ustawienie).

Jeśli albo są prywatne, albo zawierają dodatkową logikę, to o nich wspominam, w przeciwnym razie po prostu dokumentuję zamiar własności.

Byłbym szczęśliwszy z bardziej szczegółową wersją.

Drugi jest jak komentarz „licznika inkrementów” po, cóż, inkrementacji zmiennej licznika.

Oczywiste jest, że istnieje Get and Set. Gdybyś miał prywatnego setera, byłoby oczywiste, jakbyś miał prywatne słowo kluczowe.

Komentarze powinny dodawać wartość, a nie być tylko wersją komentarza do tego, czym jest kod.