Komentarze do metody Overridden w Javie

Question

Czy powinniśmy skomentować zastąpioną metodę, czy nie? Jeśli tak, to czy komentarz będzie dokumentem Java lub prostym komentarzem?

Answer 1

@ Odpowiedź SimonC wyjaśnia, w jaki sposób narzędzie javadoc generuje "odziedziczoną" dokumentację dla nadpisanych metod.

Możesz również umieścić jawne javadocs w metodzie zastąpienia i będą miały pierwszeństwo nad odziedziczonymi javadocs. Co więcej, jeśli umieścisz znacznik {@inheritDoc} w jawnym javadocs metody nadpisania, w tym miejscu zostaną uwzględnione odziedziczone komentarze.

tej odpowiedzi:

powinniśmy komentować metodę zastąpiona, czy nie? Jeśli tak, to czy komentarz będzie dokumentem Java lub prostym komentarzem?

Moim zdaniem, jeśli metoda przesłanianie uszlachetnia udokumentowane semantykę (kontrakt) sposobu zastąpionej (lub ... broń Boże ... zrywa umowę), to zasługuje, aby być udokumentowane w sposób na nadpisanie javadocs. Jeśli jednak różnice są jedynie "szczegółami implementacji", wówczas bardziej odpowiednie są proste komentarze (lub brak komentarzy).

(Jednak w praktyce uwzględnienie komentarza "non-javadoc", który odsyła czytelnika do javadoc metody nadpisanej, to IMO, marnowanie ekranu nieruchomości ... kiedy czytam kod źródłowy.)

Answer 2

Od How to Write Doc Comments for the Javadoc Tool:

Automatyczne ponowne wykorzystanie metody komentuje

Można uniknąć ponownego typowania doc komentuje będąc świadomy sposób działania narzędzia JavaDoc duplikatów (dziedziczy) Komentarze dla metod które zastępują lub implementują inne metody. Odbywa się to w trzech przypadkach: gdy metoda klasy zastępuje metodę w nadrzędnej Gdy metoda interfejsu Zastępuje metodę w superinterface Gdy metoda klasą realizuje sposób w interfejs w najpierw w dwóch przypadkach, jeżeli metoda m() przesłania inną metodę, narzędzie Javadoc będzie wygenerować podpozycję "Zastąpienie" w dokumentację dla m(), z łączem do metody, którą nadpisuje.

W trzecim przypadku, jeżeli metoda A m() w danej klasy realizuje sposób w interfejs narzędzie Javadoc będzie generowania podrubryke „określony przez” w dokumentacji m() z a link do metody, którą implementuje.

We wszystkich tych trzech przypadkach, jeśli metoda m() nie zawiera żadnych komentarzy DOC lub tagów, narzędzie Javadoc będzie również kopiować tekst metodą jest nadrzędnym lub wykonawczych do generowanej dokumentacji m(). Jeśli więc wystarcza dokumentacja zastąpionej metody lub , nie musisz dodawać dokumentacji dla dla m(). Jeśli dodasz komentarz lub komentarz do m(), nagłówek "Zastąpienie" lub "Określone przez" i link będzie nadal wyświetlany, ale tekst nie zostanie skopiowany.