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

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?

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.

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

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

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.

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.

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.