Kaj so Java ko­men­tar­ji in kako jih ustvariti

V Javi obstajajo tri različne vrste ko­men­tar­jev. Ko­men­tar­je lahko uporabite za struk­tu­ri­ra­nje in po­ja­snje­va­nje kode. Enovrstni ko­men­tar­ji so namenjeni kratkim opombam, blok ko­men­tar­ji pa so primerni za daljša pojasnila. Do­ku­men­ta­cij­ski ko­men­tar­ji pa so obsežni in ponujajo dodano vrednost, ki presega vrednost izvorne kode.

Kaj so Java ko­men­tar­ji?

Delo z izvorno kodo lahko včasih pred­sta­vlja težave, celo za izkušene raz­vi­jal­ce. Odvisno od projekta in njegovega obsega se lahko stvari hitro spre­me­ni­jo v ne­pred­vi­dlji­ve, koda pa postane zmedena. V takih trenutkih morda ne boste želeli delati na kodi sami. Toda tudi če želite, da imajo drugi dostop do vaše kode, je mogoče, da je ne bodo mogli in­tu­i­tiv­no razumeti.

Da bi se izognili ne­spo­ra­zu­mom in kodekso bolj jasno struk­tu­ri­ra­li, Java upo­rab­ni­kom omogoča pisanje ko­men­tar­jev. Ko­men­tar­je v tem pro­gram­skem jeziku lahko uporabite za po­ja­snje­va­nje svojega miselnega procesa, izračunov, metod, razredov ali struktur. Ko boste vi ali kdo drug kasneje pre­gle­do­val kodekso, bodo ko­men­tar­ji olajšali delo s kodeksom.

Da bi bili ko­men­tar­ji učin­ko­vi­ti, je pomembno, da so čim krajši. Hkrati pa morajo bralcem za­go­to­vi­ti dovolj in­for­ma­cij. Pri od­pra­vlja­nju težav so dobro obli­ko­va­ni ko­men­tar­ji bi­stve­ne­ga pomena.

Ko­men­tar­ji v Javi so na voljo v treh različnih raz­li­či­cah: enovrstni ko­men­tar­ji, blok ko­men­tar­ji (večvrstni ko­men­tar­ji) in do­ku­men­ta­cij­ski ko­men­tar­ji. Vsi ko­men­tar­ji so označeni, tako da se pri pre­va­ja­nju ne upo­šte­va­jo. V na­sle­dnjih poglavjih vam bomo pokazali, kako ustvariti ko­men­tar­je v Javi in kdaj uporabiti posamezne vrste ko­men­tar­jev.

Katere vrste ko­men­tar­jev obstajajo v Javi?

Glede na vrsto in­for­ma­cij, ki jih želite zapisati, so v Javi na voljo tri različne vrste ko­men­tar­jev. To so:

Enovrstni ko­men­tar­ji

To je naj­pre­pro­stej­ša možnost za komentar. Ta vrsta ko­men­tar­ja se ustvari z dvema za­po­re­dni­ma po­šev­ni­ca­ma (//) in ne sme biti daljša od ene vrstice. Pri eno­vr­stič­nih ko­men­tar­jih ni treba označiti konca, saj se ta samodejno doseže na koncu vrstice. Ta vrsta ko­men­tar­jev v Javi je primerna za kratke ko­men­tar­je, ki v nekaj besedah po­ja­snju­je­jo funkcijo.

Večvrstni ko­men­tar­ji

Če morajo biti vaša pojasnila nekoliko daljša, lahko uporabite večvrstne ko­men­tar­je. Te­o­re­tič­no so lahko poljubne dolžine. Primerni so za vklju­či­tev al­ter­na­tiv­nih vrstic kode, ki so iz­klju­če­ne iz kom­pi­la­ci­je, ali za podrobna pojasnila. Večvrstni ko­men­tar­ji se začnejo s poševnico in zvezdico (/*). Ko pridete do konca ko­men­tar­ja, morate samo vnesti zvezdico, ki ji sledi poševnica (*/). Besedilo med uvodno poševnico in zaključno poševnico se obravnava kot komentar in se pri kom­pi­la­ci­ji kode ne upošteva.

Ko­men­tar­ji k do­ku­men­ta­ci­ji

Medtem ko je mogoče enovrstne in večvrstne ko­men­tar­je te­o­re­tič­no vstaviti kjerkoli v izvorni kodi, so do­ku­men­ta­cij­ski ko­men­tar­ji vedno nameščeni ne­po­sre­dno pred razredi ali metodami, ki jih opisujejo. S pomočjo orodij se ti ko­men­tar­ji preberejo in povzamejo v do­ku­men­ta­ci­ji HTML. Upo­ra­blja­jo se predvsem za ustvar­ja­nje me­ta­po­dat­kov za avtorje in določene vrste pa­ra­me­trov. Ti so označeni s simbolom @. Do­ku­men­ta­cij­ski ko­men­tar­ji se začnejo s poševnico in dvema zvez­di­ca­ma (/**), končajo pa se z zvezdico in poševnico (*/).

Enovrstni ko­men­tar­ji

Da bi razumeli, kako ko­men­tar­ji v Javi delujejo v praksi, si bomo ogledali nekaj pre­pro­stih primerov. Te lahko sami pre­iz­ku­si­te in preverite izhod. Eno­vr­stič­ni komentar se začne z dvema po­šev­ni­ca­ma in je lahko sa­mo­sto­jen ali pa se nahaja za nizom navodil. **. Tako izgleda komentar v sa­mo­stoj­ni vrstici:

// Example of a single-line comment
class Main {
	public static void main(String[] args) {
	// Here is the comment
	System.out.println("This is the text that will be output at the end.");
	}
}

Če uporabite ukaz Java System.out.println, se bo prikazal samo stavek „To je besedilo, ki se izpiše na koncu“. Oba ko­men­tar­ja se bosta prikazala samo v izvorni kodi.

Al­ter­na­tiv­no lahko komentar vstavite ne­po­sre­dno za ukazom:

// Example of a single-line comment
class Main {
public static void main(String[] args) {
System.out.println("This is the text that is output at the end."); // This is the comment.
	}
}

Po­sta­vi­tev ko­men­tar­ja ne spremeni izhodnih podatkov.

Večvrstni ko­men­tar­ji

Če želite v svoj kod vstaviti večvr­stič­ni komentar, ga lahko vključite pred ali za navodili v kodu. Večvr­stič­ni ko­men­tar­ji se vedno začnejo s poševnico in zvezdico. Tukaj je večvr­stič­ni komentar pred navodili v kodu:

/* In this example there is a multi-line comment.
It starts after the asterisk.
The actual instructions for the computer are under the comment.
This is the last line of this Java comment.
*/
class Main {
public static void main(String[] args) {
System.out.println("This is the text that will be output at the end.");
	}
}

Izpis se glasi: »To je besedilo, ki bo izpisano na koncu.«.

Tukaj je navodilo, kako vstaviti komentar pod navodila:

// Example of a multi-line comment below the instructions
class Main {
public static void main(String[] args) {
System.out.println("This is the text that will be output at the end.");
/* In this example there is a multi-line comment.
It starts after the asterisk.
The actual instructions for the computer are above the comment.
This is the last line of this Java comment. */
	}
}

Izpis naj bi bil enak kot v prejšnjem primeru. Eno­vr­stič­ni komentar v prvi vrstici odlomka kode prav tako ne bo izpisan. Zvezdico in poševnico lahko postavite ne­po­sre­dno za komentar ali uporabite ločeno vrstico.

Ko­men­tar­ji k do­ku­men­ta­ci­ji

Ko­men­tar­ji v do­ku­men­ta­ci­ji delujejo podobno kot blok ko­men­tar­ji, vendar so označeni s poševnico in dvema zvez­di­ca­ma. To omogoča orodjem za do­ku­men­ta­ci­jo, da uporabijo ko­men­tar­je za ustvar­ja­nje do­ku­men­ta­ci­je. Po potrebi lahko vsebujejo tudi HTML oznake, kot so <h1>, <p> ali <strong>.

Javadoc, pri­lju­blje­no orodje, ki ga lahko upo­ra­blja­te za branje ko­men­tar­jev v do­ku­men­ta­ci­ji, uporablja tudi druge koristne oznake. Tukaj je nekaj naj­po­memb­nej­ših:

939263ef5a1ac120c2d75264caf221db

7b0ed9d2883272aca77983e730a08231