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 get
i 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.
gets or sets
lub wgets
zależności od akcesorów właściwości.Odpowiedzi:
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ę:
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.
źródło
get
Tylko 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.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:
Inną opcją, którą wymieniasz, będzie.
vs
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).
źródło
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.
źródło
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.
źródło