W dzisiejszej lekcji będzie przede wszystkim o pomaganiu sobie. Bo tak należy myśleć o dokumentacji kodu w postaci javadoc’ów.
Javadoc to narzędzie dostarczane wraz z Javą, które na podstawie kodu i dodatkowych opisów w postaci specjalnie sformatowanych komentarzy tworzy ustrukturyzowaną i spójną dokumentację kodu. Taka dokumentacja ma jedno oczywiste zastosowanie — ułatwienie pracy innym programistom z Twoim kodem poprzez wyjaśnienie za co odpowiadają poszczególne klasy, metody, pola itp. Drugie, mniej oczywiste i często zapominane, ale jakże ważne — aby pomóc sobie zrozumieć jak podzielimy algorytm / logikę na elementy, jak będą ze sobą współdziałały i co będzie ich efektem.
Lekcja
Przede wszystkim parę słów o tym, czym są javadoc — jest to technologia specyficzna dla Javy (inne języki często mają podobne narzędzia ale rozwijane osobno, przez co nie ma spójnego sposobu na dokumentację kodu, w Javie jest to część języka), która pozwala nam dodać dokumentację do niemal wszystkich elementów (klasy, metody, pakiety, pola klas, wartości Enum itp) w określonym formacie, co pozwala automatycznie wygenerować dokumentację w formacie HTML (w dalszej części lekcji zobaczysz, dlaczego to użyteczne), a także podpowiadać i pokazywać więcej informacji w środowiskach IDE.
Jeśli chodzi o sam proces generowania dokumentacji, w przypadku projektów Maven możemy ją wygenerować automatycznie używając celu javadoc:javadoc, znajdziemy ją w katalogu target/apidocs. Zawsze możemy też wygenerować ją ręcznie używając polecenia javadoc w konsoli.
Prosty komentarz — przykład
Komentarze Javadoc różnią się od zwykłych tym, że zaczynają się od /**, zamiast /* .
Najprostszy komentarz zawiera tylko i wyłącznie opis słowny całego elementu, tak jak na poniższym przykładzie (będziemy zawsze korzystali z tej samej metody aby pokazać komentarza, ale w identyczny sposób można je tworzyć dla klas i pól).
/** This method queues the email for sending. */
public boolean enqueueEmail(Email email) {
//...
}Ten komentarz zawiera prostą informację o tym, co robi dana metoda. Celem komentarzy jest nie tyle opisanie dokładnie co się dzieje w środku tej metody, ale przedstawienie jej celu — co można za jej pomocą osiągnąć. W tym kontekście można o niej myśleć jako o fragmencie dokumentacji biznesowej projektu, która jest powiązana z konkretnym kawałkiem kodu (w praktyce faktycznie są narzędzia, które generują szkielet kodu na podstawie dokumentacji, umieszczając rzeczoną dokumentację w postaci właśnie javadoców — np. używając do tego opisu przypadków użycia).
Opisujemy argumenty metody i zwracany obiekt
Javadoc pozwala nam opisywać także argumenty metody oraz elementy zwracane. Dzięki temu osoba korzystająca z klasy w przyszłości (także my sami!) łątwiej zrozumie ideę i wymagane dane. Spójrzmy na poniższy przykład
/**
* This method queues the email for sending.
* @param email An email message to be sent. The field 'from' is ignored and default value is used
* @return Whether message has been queued for sending or not
*/
public boolean enqueueEmail(Email email) {
//...
}Powyżej użyliśmy 2 tagów — @param i @return. W przypadku tagu @param musimy po spacji podać dodatkowo nazwę argumentu, którego dotyczy (możemy dokumentować wiele argumentów powielając tą linię lub też opisać tylko niektóre z argumentów, możemy też zmienić kolejność argumentów w opisie w stosunku do deklaracji metody). Javadoc to także miejsce na umieszczenie wskazówek — takich jak powyższa, która informuje, że pole from klasy Email będzie zignorowane. Należy tutaj rozgraniczyć szczegóły implementacji od wskazówek — szczegóły implementacji (których nie podajemy) to np. opis, że wiadomość ta jest dodawana do kolejki, po czym łączymy się z serwerem, którego dane odczytujemy stąd i stąd, czekamy, aż wyśle wiadomość…; wskazówka to ważna informacja z punktu widzenia używania tej metody/klasy, np. bez informacji o ignorowaniu tego pola, ktoś mógłby uznać, że implementacja nie działa, ponieważ nie zachowuje wartości pola ‘from’, które przekazał.
Odsyłanie do innych obiektów / stron www
Są trzy sposoby, aby utworzyć link do innych elementów.
Pierwszy z nich to tag @see — tworzy on wpis w specjalnej sekcji dokumentacji z etykietką ‘see also’. Możemy tutaj wpisać dowolny tekst, np. tytuł książki, opis fizycznej lokalizacji czy przedmiotu, możemy także połaczyć tą technikę z dwoma kolejnymi Przykładowe użycie:
/**
* This method queues the email for sending.
* @see Documentation of email protocols
*/
public boolean enqueueEmail(Email email) {
//...
}Drugi sposób polega na użyciu tagu @link — dzięki niemu możemy tworzyć klikalne odnośniki to innych klas/metod w dokumentacji. Co ważne, tag ten możemy wstawić w dowolnym miejscu (zarówno w opisie słownym, wewnątrz opisu przy tagu @see, wewnątrz opisu argumentu itp). Spójrzmy na poniższy przykład (klamry są istotne!):
/**
* This method queues the email for sending.
* @see Documentation of email protocols and {@link EmailProtocolService#send()}
*/
public boolean enqueueEmail(Email email) {
//...
}
W ten sposób wstawimy klikalny link, który przeniesie nas do dokumentacji metody send, która nie przyjmuje argumentów i zznajduje się w klasie EmailProtocolService. Co ważne — aby używać samej nazwy (bez pakietu), musimy mieć tę klasę zaimportowaną, w przeciwnym razie musielibyśmy użyć pełnej nazwy kwalifikowanej.
Trzeci sposób wynika z tego, że javadoc generuje dokumentacje w formacie HTML. Dzięki temu możemy używać tagów HTMLowych w opisach, tak jak w przykładzie poniżej:
/**
* This method queues the email for sending.
* @see Documentation of <a href="https://www.google.com/search?q=email%20protocols">email protocols</a> and {@link EmailProtocolService#send()}
*/
public boolean enqueueEmail(Email email) {
//...
}
Podsumowanie
Powyższe przykłady to tylko minimalna część funkcjonalności jaką oferuje javadoc, ale wystarczająca, aby tworzyć sensowne i użyteczne komentarze będące dokumentacją Twojego kodu. Często środowiska IDE wspierają ten proces, generując szkielet dokumentacji z tagami @param, @response itp uzupełnionymi, wystarczy nad klasą/metodą/polem wpisać /** i nacisnąć <enter> (przynajmniej w Eclipse).
Pamiętaj, aby przede wszystkim nie pisać bezużytecznych rzeczy — lepiej nie dodać komentarza, niż dodać bezsensowny. Polecam od czasu do czasu zapytać kolegi z zespołu, który pracował nad innymi rzeczami (lub osobę spoza zespołu), czy na podstawie tej dokumentacji (np. klasy i jej metod) jest w stanie powiedzieć, do czego ona służy i jak jej używać. Jeśli tak — dobra robota :)
Jeśli uważasz powyższą lekcję za przydatną, mamy małą prośbę: polub nasz fanpage. Dzięki temu będziesz zawsze na bieżąco z nowymi treściami na blogu ( i oczywiście, z nowymi częściami kursu Javy). Dzięki!
