Czy do implementacji należy dodać komentarze Javadoc?

Czy poprawną praktyką jest dodawanie komentarzy Javadoc w interfejsie i dodawanie komentarzy innych niż Javadoc w implementacji?

Większość IDE generuje komentarze inne niż JavaDoc dla implementacji, gdy automatycznie generujesz komentarze. Czy konkretna metoda nie powinna mieć opisu?

W przypadku metod, które są tylko implementacją (nie zastępują), z pewnością, dlaczego nie, zwłaszcza jeśli są publiczne.

Jeśli masz nadrzędną sytuację i zamierzasz powielić dowolny tekst, zdecydowanie nie. Replikacja jest niezawodnym sposobem powodowania rozbieżności. W rezultacie użytkownicy różnie rozumieliby Twoją metodę w zależności od tego, czy badają metodę w nadtypie czy podtypie. Użyj @inheritDoclub nie dostarczaj dokumentacji - środowiska IDE przyjmą najniższy dostępny tekst do użycia w widoku Javadoc.

Nawiasem mówiąc, jeśli twoja wersja nadrzędna dodaje coś do dokumentacji nadtypu, możesz być w świecie kłopotów. Przestudiowałem ten problem podczas doktoratu i odkryłem, że generalnie ludzie nigdy nie będą świadomi dodatkowych informacji w wersji nadrzędnej, jeśli odwołują się za pośrednictwem nadtypu.

Rozwiązanie tego problemu było jedną z głównych cech prototypowego narzędzia, które zbudowałem - za każdym razem, gdy wywołałeś metodę, otrzymywało się wskazanie, czy jej cel lub potencjalne nadrzędne cele zawierały ważne informacje (np. Sprzeczne zachowanie). Na przykład podczas wywoływania put na mapie przypomniano Ci, że jeśli Twoja implementacja to TreeMap, Twoje elementy muszą być porównywalne.

Zarówno implementacja, jak i interfejs powinny mieć javadoc. W przypadku niektórych narzędzi dokumentację interfejsu można odziedziczyć za pomocą słowa kluczowego @inheritDoc.

/**
 * @inheritDoc
 *
 * This implementation is very slow when b equals 3.
 */
public foo(int b)
{ ... }

Nieco dobrą praktyką jest postawienie

/**
 * {@inheritDoc}
 */

jako javadoc implementacji (chyba że jest coś do wyjaśnienia na temat szczegółów implementacji).

Generalnie, gdy zastępujesz metodę, przestrzegasz kontraktu zdefiniowanego w klasie bazowej / interfejsie, więc nie chcesz zmieniać oryginalnego javadoc. Dlatego użycie tagu @inheritDoclub @seewspomnianego w innych odpowiedziach nie jest potrzebne i służy tylko jako szum w kodzie. Wszystkie rozsądne narzędzia dziedziczą metodę javadoc z nadklasy lub interfejsu, jak określono tutaj :

Inherit from classes and interfaces - Inheriting of comments occurs in all
three possible cases of inheritance from classes and interfaces:

- When a method in a class overrides a method in a superclass
- When a method in an interface overrides a method in a superinterface
- When a method in a class implements a method in an interface

Fakt, że niektóre narzędzia (patrzę na ciebie, Eclipse!) Generują je domyślnie podczas zastępowania metody, jest tylko smutnym stanem rzeczy, ale nie usprawiedliwia zaśmiecania kodu bezużytecznym szumem.

Może być oczywiście sytuacja odwrotna, gdy faktycznie chcesz dodać komentarz do metody nadpisywania (zwykle dodatkowe szczegóły implementacji lub nieco zaostrzenie kontraktu). Ale w tym przypadku prawie nigdy nie chcesz robić czegoś takiego:

/**
 * {@inheritDoc}
 *
 * This implementation is very, very slow when b equals 3.
 */

Czemu? Ponieważ odziedziczony komentarz może być bardzo długi. W takim przypadku, kto zauważy dodatkowe zdanie na końcu 3 długich akapitów? Zamiast tego po prostu zapisz fragment swojego komentarza i to wszystko. Wszystkie narzędzia javadoc zawsze pokazują link Określony przez, który można kliknąć, aby przeczytać komentarz klasy bazowej. Nie ma sensu ich mieszać.

@see Generuje link do opisu w interfejsie. Ale myślę, że dobrze jest też dodać kilka szczegółów dotyczących implementacji.

Sjoerd słusznie mówi, że zarówno interfejs, jak i implementacja powinny mieć JavaDoc. Interfejs JavaDoc powinien definiować kontrakt metody - co metoda ma robić, jakie dane wejściowe przyjmuje, jakie wartości ma zwracać i co ma zrobić w przypadku błędu.

Dokumentacja wdrożeniowa powinna uwzględniać rozszerzenia lub ograniczenia kontraktu, a także odpowiednie szczegóły wdrożenia, w szczególności wykonania.

Ze względu na wygenerowany javadoc tak, ma to znaczenie. Jeśli zadeklarujesz odniesienia do konkretnej implementacji przy użyciu tylko interfejsu, nie zrobisz tego, ponieważ metody interfejsu zostaną pobrane przez IDE.