#24 – Komentujemy kod

By 23 kwietnia 2015Kurs Javy

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 :)

Zadanie

Dodaj komentarze Javadoc do całego kodu, który już napisałaś. Odpowiednio opisz także wyjątki i typy zwracane oraz przyjmowane argumenty metod.

Licencja Creative Commons

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!

  •  
  •  
  •  
  •  
  •