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

19

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.

Tomas
źródło
szczerze mówiąc, jedyną rzeczą, jaką daje mi komentarz, którego nie ma w kodzie (zakładając, że jest to użytkownik), jest to, że identyfikator jest unikalny. więc żadne z nich nie jest „konieczne”.
jk.
@Tomas - czy zainstalowałeś wtyczkę GhostDoc ? wygeneruje dla ciebie dobre komentarze XML, jeśli użyjesz dobrych nazw właściwości na początek i automatycznie umieścisz gets or setslub w getszależności od akcesorów właściwości.
Trevor Pilley,
@ Trevor - Mam go zainstalowany. Właśnie myślałem, czy powinienem zmienić jego szablony i usunąć „Pobiera lub ustawia”, czy nie :). Jest to jednak świetna wtyczka.
Tomas
Witamy w świecie nieudokumentowania .
Pułkownik Panic

Odpowiedzi:

28

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:

wprowadź opis zdjęcia tutaj

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

wprowadź opis zdjęcia tutaj wprowadź opis zdjęcia tutaj wprowadź opis zdjęcia tutaj

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.

wprowadź opis zdjęcia tutaj

Mikrofon
źródło
Dzięki za dokładną odpowiedź. Myślę, że są to niestety ograniczenia Visual Studio IDE. Myślałem o tym i myślę, że inteligencja mogłaby pokazać, które właściwości są, np., getTylko w obecnym kontekście. Wygięcie dokumentacji w celu dopasowania do określonego środowiska programistycznego nie jest zbyt wygodne. Nadal uważam, że Visual Studio i C # są tak ściśle powiązane, że może to być właściwe rozwiązanie.
Tomas
1
@Tomas Zgadzam się, że Visual Studio powinno robić większe rozróżnienie. Z pewnością cieszę się, że mogę podać czerwoną, krętą linię w momencie, gdy niewłaściwie używam nieruchomości.
Mike
2

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

NikolaiDante
źródło
2

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.

CLandry
źródło
1

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.

ozz
źródło