#24 — Komentujemy kod

By 23 kwietnia 2015Kurs Javy

W dzisiejszej lekcji będzie przede wszys­tkim o poma­ganiu sobie. Bo tak należy myśleć o doku­men­tacji kodu w postaci javadoc’ów.

Javadoc to narzędzie dostar­czane wraz z Javą, które na pod­staw­ie kodu i dodatkowych opisów w postaci spec­jal­nie sfor­ma­towanych komen­tarzy tworzy ustruk­tu­ry­zowaną i spójną doku­men­tację kodu. Taka doku­men­tac­ja ma jed­no oczy­wiste zas­tosowanie — ułatwie­nie pra­cy innym pro­gramis­tom z Twoim kodem poprzez wyjaśnie­nie za co odpowiada­ją poszczególne klasy, metody, pola itp. Drugie, mniej oczy­wiste i częs­to zapom­i­nane, ale jakże ważne — aby pomóc sobie zrozu­mieć jak podzie­limy algo­rytm / logikę na ele­men­ty, jak będą ze sobą współdzi­ałały i co będzie ich efek­tem.

Lekcja

Przede wszys­tkim parę słów o tym, czym są javadoc — jest to tech­nolo­gia specy­ficz­na dla Javy (inne języ­ki częs­to mają podob­ne narzędzia ale rozwi­jane osob­no, przez co nie ma spójnego sposobu na doku­men­tację kodu, w Javie jest to część języ­ka), która pozwala nam dodać doku­men­tację do niemal wszys­t­kich ele­men­tów (klasy, metody, paki­ety, pola klas, wartoś­ci Enum itp) w określonym for­ma­cie, co pozwala automaty­cznie wygen­erować doku­men­tację w for­ma­cie HTML (w dal­szej częś­ci lekcji zobaczysz, dlaczego to użyteczne), a także pod­powiadać i pokazy­wać więcej infor­ma­cji w środowiskach IDE.

Jeśli chodzi o sam pro­ces gen­erowa­nia doku­men­tacji, w przy­pad­ku pro­jek­tów Maven może­my ją wygen­erować automaty­cznie uży­wa­jąc celu javadoc:javadoc,  zna­jdziemy ją w kat­a­logu target/apidocs. Zawsze może­my też wygen­erować ją ręcznie uży­wa­jąc polece­nia javadoc w kon­soli.

Prosty komentarz — przykład

Komen­tarze Javadoc różnią się od zwykłych tym, że zaczy­na­ją się od /**, zami­ast /* .

Najprost­szy komen­tarz zaw­iera tylko i wyłącznie opis słowny całego ele­men­tu, tak jak na poniższym przykładzie (będziemy zawsze korzys­tali z tej samej metody aby pokazać komen­tarza, ale w iden­ty­czny sposób moż­na je tworzyć dla klas i pól).

/** This method queues the email for sending. */
public boolean enqueueEmail(Email email) {
    //...
}

Ten komen­tarz zaw­iera prostą infor­ma­cję o tym, co robi dana meto­da. Celem komen­tarzy jest nie tyle opisanie dokład­nie co się dzieje w środ­ku tej metody, ale przed­staw­ie­nie jej celu — co moż­na za jej pomocą osiągnąć. W tym kon­tekś­cie moż­na o niej myśleć jako o frag­men­cie doku­men­tacji biz­ne­sowej pro­jek­tu, która jest pow­iązana z konkret­nym kawałkiem kodu (w prak­tyce fak­ty­cznie są narzędzia, które generu­ją szkielet kodu na pod­staw­ie doku­men­tacji, umieszcza­jąc rzec­zoną doku­men­tację w postaci właśnie javadoców — np. uży­wa­jąc do tego opisu przy­pad­ków uży­cia).

Opisujemy argumenty metody i zwracany obiekt

Javadoc pozwala nam opisy­wać także argu­men­ty metody oraz ele­men­ty zwracane. Dzię­ki temu oso­ba korzys­ta­ją­ca z klasy w przyszłoś­ci (także my sami!) łątwiej zrozu­mie ideę i wyma­gane 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 przy­pad­ku tagu @param musimy po spacji podać dodatkowo nazwę argu­men­tu, którego doty­czy (może­my doku­men­tować wiele argu­men­tów powiela­jąc tą lin­ię lub też opisać tylko niek­tóre z argu­men­tów, może­my też zmienić kole­jność argu­men­tów w opisie w sto­sunku do deklaracji metody). Javadoc to także miejsce na umieszcze­nie wskazówek — takich jak powyższa, która infor­mu­je, że pole from klasy Email będzie zig­norowane. Należy tutaj roz­graniczyć szczegóły imple­men­tacji od wskazówek — szczegóły imple­men­tacji (których nie poda­je­my) to np. opis, że wiado­mość ta jest dodawana do kole­j­ki, po czym łączymy się z ser­w­erem, którego dane odczy­tu­je­my stąd i stąd, czekamy, aż wyśle wiado­mość…; wskazówka to waż­na infor­ma­c­ja z punk­tu widzenia uży­wa­nia tej metody/klasy, np. bez infor­ma­cji o ignorowa­niu tego pola, ktoś mógł­by uznać, że imple­men­tac­ja nie dzi­ała, ponieważ nie zachowu­je wartoś­ci pola ‘from’, które przekazał.

Odsyłanie do innych obiektów / stron www

Są trzy sposo­by, aby utworzyć link do innych ele­men­tów.

Pier­wszy z nich to tag @see — tworzy on wpis w spec­jal­nej sekcji doku­men­tacji z etyki­etką ‘see also’. Może­my tutaj wpisać dowol­ny tekst, np. tytuł książ­ki, opis fizy­cznej lokaliza­cji czy przed­mio­tu, może­my także połaczyć tą tech­nikę z dwoma kole­jny­mi Przykład­owe uży­cie:

/**
* This method queues the email for sending.
* @see Documentation of email protocols
*/
public boolean enqueueEmail(Email email) {
    //...
}

Dru­gi sposób pole­ga na uży­ciu tagu @link — dzię­ki niemu może­my tworzyć klikalne odnośni­ki to innych klas/metod w doku­men­tacji. Co ważne, tag ten może­my wstaw­ić w dowol­nym miejs­cu (zarówno w opisie słownym, wewnątrz opisu przy tagu @see, wewnątrz opisu argu­men­tu itp). Spójrzmy na poniższy przykład (klam­ry 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 wstaw­imy klikalny link, który prze­niesie nas do doku­men­tacji metody send, która nie przyj­mu­je argu­men­tów i zzna­j­du­je się w klasie Email­Pro­to­colSer­vice. Co ważne — aby uży­wać samej nazwy (bez paki­etu), musimy mieć tę klasę zaim­por­towaną, w prze­ci­wnym razie musielibyśmy użyć pełnej nazwy kwal­i­fikowanej.

Trze­ci sposób wyni­ka z tego, że javadoc generu­je doku­men­tac­je w for­ma­cie HTML. Dzię­ki temu może­my uży­wać tagów HTM­Lowych 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 min­i­mal­na część funkcjon­al­noś­ci jaką ofer­u­je javadoc, ale wystar­cza­ją­ca, aby tworzyć sen­sowne i użyteczne komen­tarze będące doku­men­tacją Two­jego kodu. Częs­to środowiska IDE wspier­a­ją ten pro­ces, generu­jąc szkielet doku­men­tacji z taga­mi @param, @response itp uzu­pełniony­mi, wystar­czy nad klasą/metodą/polem wpisać /** i nacis­nąć (przy­na­jm­niej w Eclipse).

Pamię­taj, aby przede wszys­tkim nie pisać bezużytecznych rzeczy — lep­iej nie dodać komen­tarza, niż dodać bezsen­sowny. Pole­cam od cza­su do cza­su zapy­tać kole­gi z zespołu, który pra­cow­ał nad inny­mi rzecza­mi (lub osobę spoza zespołu), czy na pod­staw­ie tej doku­men­tacji (np. klasy i jej metod) jest w stanie powiedzieć, do czego ona służy i jak jej uży­wać. Jeśli tak — dobra rob­o­ta :)

Zadanie

Dodaj komen­tarze Javadoc do całego kodu, który już napisałaś. Odpowied­nio opisz także wyjąt­ki i typy zwracane oraz przyj­mowane argu­men­ty metod.

Licencja Creative Commons

Jeśli uważasz powyższą lekcję za przy­dat­ną, mamy małą prośbę: pol­ub nasz fan­page. Dzię­ki temu będziesz zawsze na bieżą­co z nowy­mi treś­ci­a­mi na blogu ( i oczy­wiś­cie, z nowy­mi częś­ci­a­mi kur­su Javy). Dzię­ki!

  •  
  •  
  •  
  •  
  •