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