Chcę napisać Javadoc w SUCHY sposób. Ale dokument wyroczni o Javadoc mówi, że napisz to samo w komentarzu metody przeciążenia. Czy nie mogę uniknąć powtórzeń?
Chcę napisać Javadoc w SUCHY sposób. Ale dokument wyroczni o Javadoc mówi, że napisz to samo w komentarzu metody przeciążenia. Czy nie mogę uniknąć powtórzeń?
Odpowiedzi:
Posypuję {@inheritDoc}dyrektywy tu i tam w moich komentarzach Javadoc, gdy zastępuję metody z nadklas lub implementuję metody zdefiniowane w interfejsie.
Działa to przynajmniej dla mnie dobrze, pozwala uniknąć powtórzeń w kodzie źródłowym, a jeśli chcesz, możesz dodać szczegółowe informacje do konkretnego komentarza Javadoc. Nie uważam, że sam komentarz Javadoc nie stanowi prawie żadnego problemu, gdy wystarczy przyzwoitego IDE, aby najechać kursorem myszy na nazwę powiązanego identyfikatora, aby uzyskać renderowany Javadoc z referencjami i wszystkim.
Dokumentacja ma na celu oświecenie przyszłych użytkowników przedmiotu. Dzieje się tak częściowo dla wygody autora, aby nie trzeba było się z nim kontaktować, ilekroć ktoś nie może dowiedzieć się, jak to działa. Przeważnie jest to jednak z korzyścią dla osób, które muszą używać lub wspierać rzecz.
W związku z tym chodzi o jasność, a nie o wygodę autora. Nie możesz oczekiwać, że ludzie będą przeszukiwać dokumentację API, ponieważ byłeś zbyt leniwy, aby się powtarzać. Ssij to - Javadoc będzie powtarzalny.
To powiedziawszy, nie ma powodu, jeśli jesteś sprytny, nie możesz napisać programu, który wstawiałby komentarze do kodu na podstawie markerów lub innych kryteriów. Może to być więcej kłopotów niż jest to warte. Albo nie.