Preskoči na glavni sadržaj

Uči se Java sa mnom: upoznavanje sa Java komentarima

Chenmo Wang ErJava jezgroOsnove Java sintakse888 reči3 minuta

"Erge, čini se da zaista nema mnogo toga za reći o komentarima u Javi, već sam unapred pogledao — to su samo jednoredni, višeredni i dokumentacioni komentari." Na Sanmejzinom licu pojavio se sladak osmeh; zapravo je unapred pregledala gradivo koje je predstojeće, ostavljajući utisak "tri dana bez viđenja i vredi divljenja".

"Vrste komentara zaista nisu brojne, ali su prilično zanimljive; saslušaj kako će ti brat da ti objasni."

01,Jednoredni komentar

Jednoredni komentari se obično koriste za objašnjenje namene pojedinog reda koda unutar metoda.

public void method() {
    int age = 18; // age označava uzrast
}

Međutim, pisanje na kraju reda zapravo ne odgovara razvojnim smernicama kompanije Alibaba.

Pravilan jednoredni komentar je, kao što je prikazano gore, u posebnom redu iznad komentarisane naredbe, koristeći //.

public void method() {
    // age označava uzrast
    int age = 18;
}

02,Višeredni komentar

Višeredni komentari se zapravo ne koriste često; obično služe za objašnjenje namene jednog bloka koda.

/*
age označava uzrast
name označava ime
*/
int age = 18;
String name = "Chenmo Wang Er";

Počinje sa /*, završava se sa */, ali je praktičnije koristiti više // jer se * i / ne nalaze jedno pored drugog, pa je kucanje nezgrapno.

// age označava uzrast
// name označava ime
int age = 18;
String name = "Chenmo Wang Er";

03,Dokumentacioni komentar

Dokumentacioni komentar se može koristiti na tri mesta — klase, polja i metode — da objasni čemu služe.

/**
 * Erge
 */
public class Demo {
    /**
     * uzrast
     */
    private int age;

    /**
     * main metod kao ulazna tačka programa
     *
     * @param args argumenti
     */
    public static void main(String[] args) {

    }
}

PS: U Intellij IDEA, nakon unosa /** i pritiska na taster Enter automatski se dodaje format dokumentacionog komentara, a */ se automatski dovršava.

Dalje, pogledajmo kako pomoću komande javadoc generisati dokumentaciju koda.

Prvi korak, kliknite desnim klikom na taj fajl klase i izaberite "Open in Terminal" da otvorite prozor komandne linije.

Drugi korak, izvršite komandu javadoc javadoc Demo.java -encoding utf-8. Parametar -encoding utf-8 osigurava da kineski znakovi ne budu prikazani neispravno.

Treći korak, izvršavanjem komande ls -l mogu se videti datoteke nastale pri generisanju dokumentacije koda — uglavnom html, js i css datoteke koje zajedno čine veb stranicu.

Četvrti korak, izvršavanjem komande open index.html dokumentacioni komentar se otvara u podrazumevanom pregledaču.

Klikom na "Demo" može se pregledati detaljnija dokumentacija te klase.

04,Stvari na koje treba paziti kod dokumentacionih komentara

  1. Komanda javadoc može da generiše dokumentaciju samo za polja, metode i klase modifikovane sa public i protected.

Komentari za polja i metode modifikovane sa default i private biće zanemareni, jer inače i ne želimo da ta polja i metode budu izložena onima koji pozivaju.

Ako klasa nije public, izvršavanje komande javadoc neće uspeti.

  1. U dokumentacione komentare mogu se ugraditi neke HTML oznake, poput oznake za pasus <p>, oznake za hiperlink <a></a> itd., ali ne koristite oznake za naslove poput <h1>, jer javadoc umeće sopstvene naslove i lako dolazi do sukoba.

  2. U dokumentacione komentare mogu se umetnuti neke @ anotacije, na primer @see za referencu na drugu klasu, @version za broj verzije, @param za identifikator parametra, @author za identifikator autora, @deprecated za obeležavanje kao zastarelo itd.

05,Smernice za komentare

  1. Klase, polja i metode moraju koristiti dokumentacione komentare, a ne jednoredne i višeredne komentare. Dokumentacioni komentari u IDE prozoru za uređivanje pružaju lebdeći prikaz, što povećava efikasnost kodiranja.

Na primer, pri korišćenju klase String, kada se mišem pređe preko String dobija se sledeći prikaz.

  1. Sve apstraktne metode (uključujući metode u interfejsima) moraju imati Javadoc komentar; pored povratne vrednosti, parametara i opisa izuzetaka, mora se navesti šta taj metod radi i koju funkciju ostvaruje.

  2. Sve klase moraju imati navedenog autora i datum kreiranja.

U Intellij IDEA to se može podesiti u "File and Code Templates".

Sintaksa je sledeća:

/**
* Erge
* @author Chenmo Wang Er
* @date ${DATE}
*/

Nakon podešavanja, pri kreiranju nove klase automatski se generiše.

/**
 * Erge
 *
 * @author Chenmo Wang Er
 * @date 2020/11/16
 */
public class Test {
}

  1. Sva polja tipa enumeracije moraju imati komentar koji objašnjava namenu svake stavke podataka.

  2. Kada se kod menja, i komentar mora biti adekvatno izmenjen.

"Dobro, Sanmej, toliko o komentarima u Javi za sada." rekao sam Sanmej okrećući ukočeni vrat. "Zapamti jedno — komentar je sastavni deo programa."

  • Prvo, komentar mora tačno da odražava dizajnerske ideje i logiku koda;
  • Drugo, komentar mora da opiše poslovno značenje, tako da drugi programeri brzo razumeju informacije koje stoje iza koda.

Veliki blok koda bez ijednog komentara za čitaoca je poput nerazumljivog teksta; komentari su za sebe — čak i nakon dužeg vremena omogućavaju jasno razumevanje tadašnjeg razmišljanja; komentari su i za naslednika, da bi brzo preuzeo vaš posao.