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 )
{
...
}
Summary
i w returns
zasadzie mówią to samo. Często kończę pisanie streszczenia bardziej z returns
perspektywy, returns
cał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
.
- Dlaczego miałbyś kiedykolwiek dokumentować
returns
osobnosummary
? - Wszelkie informacje na temat tego, dlaczego Microsoft przyjął ten standard?
źródło
Moje użycie:
<summary>
opisuje, co robi metoda (aby uzyskać<returns>
).<returns>
opisuje zwracaną wartość .Odnośniki do MSDN:
<summary>
.<returns>
źródło
summary
stanu 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. ; ptrue
jeśli predykat został dopasowany”. Jeśli ktoś musi wiedzieć, co stanowi dopasowanie, może przeczytać resztę dokumentacji.<summary>
i<returns>
zrób to”. Jak powiedział Blrfl, jest to tylko wskazówka, której można lub nie chcieć używać.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.
źródło
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 ...
źródło
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.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:
staje się
źródło
returns
Microsoft jest zdecydowanie za długi. Jeśli powinien coś zrobić, to po prostu zapewnić, że prawda oznacza, że pasuje, a fałsz, że nie.