Czy komentarz do metody powinien zawierać zarówno podsumowanie, jak i zwrócony opis, gdy często są tak podobne?

10

Jestem zwolenniczką odpowiednio udokumentowanego kodu i doskonale zdaję sobie sprawę z jego wad . To nie wchodzi w zakres tego pytania.

Lubię przestrzegać zasady dodawania komentarzy XML dla każdego członka publicznego, biorąc pod uwagę, jak bardzo lubię IntelliSense w Visual Studio.

Jest jednak jedna forma redundancji, która przeszkadza nawet tak nadmiernemu komentatorowi jak ja. Jako przykład weź List.Exists () .

/// <summary>
///     Determines whether the List<T> contains elements
///     that match the conditions defined by the specified predicate.
/// </summary>
/// <returns>
///     true if the List<T> contains one or more elements that match the
///     conditions defined by the specified predicate; otherwise, false.
/// </returns>
public bool Exists( Predicate<T> match )
{
    ...
}

Summaryi w returnszasadzie mówią to samo. Często kończę pisanie streszczenia bardziej z returnsperspektywy, returnscałkowicie odrzucając dokumentację.

Zwraca true, gdy lista zawiera elementy spełniające warunki zdefiniowane przez określony predykat, w przeciwnym razie false.

Dodatkowo dokumentacja zwrotów nie pojawia się w IntelliSense, więc raczej piszę w niej wszelkie istotne informacje summary.

  1. Dlaczego miałbyś kiedykolwiek dokumentować returnsosobno summary?
  2. Wszelkie informacje na temat tego, dlaczego Microsoft przyjął ten standard?
Steven Jeuris
źródło

Odpowiedzi:

3

Możesz wnioskować jeden od drugiego, ale te dwie sekcje pozostają osobne, ponieważ pomaga skupić się na tej, która interesuje osobę podczas przeglądania / używania kodu .

Biorąc twój przykład, wolałbym napisać:

/// <summary>
/// Determines whether the List<T> contains elements that match the conditions
/// defined by the specified predicate.
/// </summary>
/// <returns>
/// A value indicating whether at least one element matched the predicate.
/// </returns>
public bool Exists(Predicate<T> match)
{
    ...
}
  • Jeśli przeglądam ten kod i chcę wiedzieć, co robi metoda, czytam podsumowanie i to wszystko, na czym mi zależy.

  • Teraz wyobraźmy sobie, że używam twojej metody, a zwracana wartość jest dziwna, biorąc pod uwagę dane wejściowe. Teraz tak naprawdę nie chcę wiedzieć, co robi metoda, ale chcę wiedzieć coś więcej o wartości zwracanej. Tutaj <returns/>sekcja pomaga i nie muszę czytać podsumowania.

Ponownie w tym przykładzie można wnioskować z podsumowania <returns/>i wnioskować o oczekiwanej wartości zwrotu z podsumowania. Ale biorąc pod uwagę ten sam argument do końca, nie ma potrzeby dokumentowania twojej metody w tym przypadku: nazwa metody, umieszczona w środku List<T>, Predicate<T> matchjako jedyny argument jest sama w sobie dość wyraźna.

Pamiętaj, kod źródłowy jest zapisywany raz, ale czytany wiele razy . Jeśli możesz zmniejszyć akcyzę dla kolejnych czytelników kodu, spędzając dziesięć sekund na pisaniu dodatkowego zdania w dokumentacji XML, zrób to.

Arseni Mourzenko
źródło
1
wywołujesz metodę i nie chcesz wiedzieć, co ona robi !?
jk.
1
@jk: Sugeruje, że już to zrobił. Tylko wtedy, gdy zawiedzie, chce „skoncentrować się” na wartości zwracanej. +1 za ostatni akapit, tak też zasadniczo się czuję. Nawet jeśli dokumentacja podaje oczywisty fakt, tak jak w moim przykładzie, uspokaja czytelnika o jego oczekiwaniach. Gdy komentarze są odpowiednio zarządzane, napisane jest: „ta metoda jest właściwie przemyślana i nie robi nic więcej niż to, co tu wspomniano”, jak w dokumentacji msdn.
Steven Jeuris,
2

Moje użycie:
<summary>opisuje, co robi metoda (aby uzyskać <returns>).
<returns>opisuje zwracaną wartość .

Odnośniki do MSDN: <summary>.<returns>

Jake Berger
źródło
Dzięki za link. Ale nigdzie dokumentacja msdn summarystanu nie opisuje „tego, co robi metoda”. Głosowałem w dół, dopóki nie poświęcisz czasu, aby zaktualizować swoją odpowiedź, aby wyjaśnić różnicę między stanami msdn a tym, co sformułujesz. ; p
Steven Jeuris
2
Niezależnie od tego, czy MSDN mówi coś na ten temat, czy nie, jest to dobra wskazówka. W swoim przykładzie nie musisz powtarzać całego podsumowania, możesz po prostu powiedzieć „zwraca, truejeśli predykat został dopasowany”. Jeśli ktoś musi wiedzieć, co stanowi dopasowanie, może przeczytać resztę dokumentacji.
Blrfl,
@Blrfl: Nie twierdzę, że wytyczne są złe. Mówię, że odwoływanie się do źródła jest błędem, co sugeruje, że coś tam jest napisane, gdy tak nie jest. Stąd głosowanie w dół. Bardzo chciałbym zobaczyć tę odpowiedź zredagowaną.
Steven Jeuris,
@StevenJeuris: Linki do dokumentacji MSDN były jedynie informacjami uzupełniającymi. MSDN NIE mówi: „Kiedy masz a <summary>i <returns>zrób to”. Jak powiedział Blrfl, jest to tylko wskazówka, której można lub nie chcieć używać.
Jake Berger,
1
@StevenJeuris: Chociaż ze względu na sposób, w jaki został napisany, mogłem zobaczyć, jak ktoś może wywnioskować, że pochodzi on z MSDN.
Jake Berger,
1

Dlaczego miałbyś kiedykolwiek dokumentować zwroty oddzielnie od podsumowania?

Myślę, że jeśli część podsumowująca jest naprawdę długa i opisowa, warto mieć osobną, krótką część zwrotną na końcu.

Zwykle piszę tylko <summary>część własnego kodu, formułując to tak, jak napisałeś „Zwraca _ ”.

Wstawiam wszelkie uwagi, które powinien wiedzieć osoba dzwoniąca, które nie są oczywiste z nazwy metody i parametrów (i ich nazw). Mamy jednak nadzieję, że nazwa metody i parametry sprawiają, że komentarz jest wystarczająco oczywisty.

Philip
źródło
1

Ostatnio rozdarło mnie to samo filozoficzne pytanie i wciąż nie jestem pewien, jakie jest dobre rozwiązanie. Ale do tej pory takie było moje podejście ...

  • Dokumentacja metody opisuje tylko to, co dzwoniący zewnętrzni powinni wiedzieć. Nie mówi o tym, jak ta praca jest wykonywana wewnętrznie, ale wspomina: a) dlaczego dzwoniący chciałby wywołać tę metodę, b) jakie byłyby oczekiwane wyniki wywołania tej metody. Jeśli istnieje potrzeba udokumentowania działania tej metody, umieszczam ją w samym ciele kodu.
  • Jeśli metoda ma wystarczającą złożoność, ogólny opis i osobna sekcja [zwroty] wydają się uzasadnione. Nie chcesz, aby czytelnik czytał cały opis i próbował wywnioskować, jak interpretować zwracaną wartość.
  • Jeśli metoda jest tak prosta, że ​​najlepszym sposobem na opisanie jej działania jest powiedzenie czegoś takiego: „Ta metoda zwraca adres osoby”, pomijam sekcję [zwroty], ponieważ dodawanie wydaje się być sprzeczne z zasadą DRY, a ja wielki zwolennik tego. Wydaje się, że wiele metod jednowierszowych należy do tej kategorii.
DXM
źródło
Tak, mogę łączyć się z wymienionymi punktami i mniej więcej podążać za nimi. Problem polega na tym, że jest to dość subiektywna konwencja, co może być powodem, dla którego Microsoft po prostu zdecydował się zawsze dodawać returns. Zauważam też, że zawsze używają tego samego sformułowania, np. „Prawda, jeśli ...; w przeciwnym razie fałsz ”. Zastanawiam się, czy oni również określili konwencję w tym zakresie.
Steven Jeuris,
0

Podsumowanie powinno być tak opisowe, jak mogłoby być przydatne; opisy parametrów i zwracanej wartości powinny być krótkie i słodkie. Jeśli masz wybór między jednym słowem a pięcioma, użyj jednego. Zaostrzmy twój przykład:

true, jeśli lista zawiera jeden lub więcej elementów, które spełniają warunki określone przez określony predykat; w przeciwnym razie fałsz.

staje się

true, jeśli dowolny element listy pasuje do predykatu; inaczej fałszywe.

Caleb
źródło
Właściwie napisanie tego w ten sposób uświadomiło mi zaletę standardowego sposobu Microsoftu, zaczynając od „Określa, czy ...” . Wydaje mi się, że jest bardziej czytelny, ponieważ najpierw wyjaśnia, co robi, zanim powie, jaki jest tego wynik. To o krok mniej od pośrednictwa. Zgadzam się, że returnsMicrosoft jest zdecydowanie za długi. Jeśli powinien coś zrobić, to po prostu zapewnić, że prawda oznacza, że ​​pasuje, a fałsz, że nie.
Steven Jeuris,