Javadoc - jak poprawnie zrobić dokumentację?

0

Pierwszy raz robię dokumentację w javie. Chciałbym się dowiedzieć co trzeba opisywać w komentarzach. Klasy metody zmienne czy cały kod? Czy w netbinsie też jest jakiś skrót jak w eclipse do dodawania komentarzy? W eclipse to chyba bylo alt shift j.

2

Kod powinien się sam komentować ;)
A tak to:

  • klasy - na zasadzie "do czego ta klasa służy"
  • metody - jw, plus szczególnie opis parametrów i wartości zwracanej, szczególnie jeśli używasz prymitywów
1

Po pierwsze jak wspominał @Shalom nazewnictwo powinno spełniać zasadę "samokomentowania" kodu. Jednak javadoc też jest dobry. Co w nim? Dodatkowe informacje nie wynikające wprost z nazwy. Przykładowo w stosunku do parametrów dopuszczalność wartości null (o ile nie używasz adnotacji), w przypadku zwracanych wartości czy zwracany jest null jak tak to kiedy. W przypadku implementacji interfejsów rozwinięcie i krótkie omówienie co siedzi w środku. Przykładowo klasa implementuje interfejs Sorter mający metodę sort w javadocu napisał bym przynajmniej jakiego algorytmu używam do sortowania.
Jeśli chodzi o klasy to warto napisać do jakiego punktu specyfikacji odnosi się dana klasa. Dzięki temu wyszukiwanie klas "po specce" nie będzie uciążliwe. Przydatne w dużych projektach, a w mniejszych warto w celu wyrobienia sobie nawyku.
Podobnie jak mamy wiele implementacji tego samego interfejsu to warto wspomnieć czym się różnią. Względnie z jakich dodatkowych zasobów korzystają. Na przykład dla klasy RaportPdfPrinter informacja, że używasz iReport, a nie iText jest ważna jeżeli gdzie indziej do tworzenia pdfów używasz "gołego" iTexta.

1 użytkowników online, w tym zalogowanych: 0, gości: 1