Czy do implementacji należy dodać komentarze Javadoc?

109

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?

— Vaishak Suresh
źródło

67

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.

— Uri
źródło

1

Czy nie wiesz już, że elementy muszą być porównywalne podczas korzystania z TreeMap? Implementacja również nie powinna implementować zachowania sprzecznego.

— Jimmy T.

1

Myślę, że to powinna być poprawna odpowiedź stackoverflow.com/a/39981265/419516

— user219882

26

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)
{ ... }

— Sjoerd
źródło

5

Czym dokładnie są „niektóre narzędzia”? Czy działa po wyjęciu z pudełka, czy jest powiązany z określonymi wtyczkami.

— jediz

Wiem, że Eclipse używa {@inheritDoc}i działa tylko wtedy, gdy nie masz @Overridenajpierw adnotacji

— ksnortum

24

Nieco dobrą praktyką jest postawienie

/**
 * {@inheritDoc}
 */

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

— Wania
źródło

2

Istotą interfejsu jest to, że metodę można zaimplementować na wiele sposobów. Jeśli mam odziedziczyć komentarze, jaki jest sens umieszczania ich w implementacji?

— Vaishak Suresh

16

Używam powyższego tagu, a następnie umieszczam dodatkową wymaganą dokumentację poniżej tagu.

— Ben Page

17

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ć.

— Natix
źródło

6

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

— redben
źródło

6

IMO używanie @seelinkowania do metod interfejsu jest dobrą praktyką iw większości przypadków wystarcza. Kiedy kopiujesz javadoc z metody interfejsu do konkretnej implementacji, po prostu kopiujesz informacje i może to szybko stać się niespójne. Jednak wszelkie dodatkowe informacje o implementacji należy dodać do javadoc.

— Piotr

1

Dodatkowy dokument nie dotyczy kopiowania dokumentu z interfejsu, ale tylko po to, aby wyjaśnić, w jaki sposób implementujesz metodę i tym podobne. Za pomocą dokumentu interfejsu wyjaśnij, jakie wyniki / cele (stan aplikacji lub zwracana metoda), podczas gdy w Twojej implementacji dobrze byłoby wyjaśnić, w jaki sposób osiągasz te cele.

— redben

4

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.

— DJClayworth
źródło

0

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.

— Boris Pavlović
źródło