Mitä ovat Java-kommentit ja miten niitä luodaan?

Java-kielessä on kolme erilaista kom­ment­ti­tyyp­piä. Kom­ment­te­ja voi käyttää koodin jä­sen­tä­mi­seen ja se­lit­tä­mi­seen. Yk­si­ri­vi­set kommentit ovat lyhyitä muis­tiin­pa­no­ja, kun taas loh­ko­kom­men­tit sopivat pidempiin se­li­tyk­siin. Do­ku­men­taa­tio­kom­men­tit puo­les­taan ovat laajoja ja tarjoavat lisäarvoa läh­de­koo­din lisäksi.

Mitä ovat Java-kommentit?

Läh­de­koo­din parissa työs­ken­te­ly voi joskus aiheuttaa ongelmia jopa ko­ke­neil­le ke­hit­tä­jil­le. Pro­jek­tis­ta ja sen laa­juu­des­ta riippuen tilanne voi muuttua nopeasti ar­vaa­mat­to­mak­si ja koodi sekavaksi. Täl­lai­sis­sa ti­lan­teis­sa et ehkä halua työs­ken­nel­lä koodin parissa yksin. Mutta vaikka ha­luai­sit­kin muiden pääsevän käsiksi koodiisi, he eivät vält­tä­mät­tä pysty ym­mär­tä­mään sitä in­tui­tii­vi­ses­ti.

Vää­rin­kä­si­tys­ten vält­tä­mi­sek­si ja koodin sel­keäm­män jä­sen­te­lyn hel­pot­ta­mi­sek­si Java tarjoaa käyt­tä­jil­le mah­dol­li­suu­den kir­joit­taa kom­ment­te­ja. Voit käyttää kom­ment­te­ja tässä oh­jel­moin­ti­kie­les­sä se­lit­tä­mään ajat­te­lupro­ses­sia­si, las­kel­mia­si, me­ne­tel­miä­si, luokkia tai ra­ken­tei­ta. Kun sinä tai joku muu tar­kas­te­lee koodia myöhemmin, kommentit hel­pot­ta­vat koodin kä­sit­te­lyä.

Jotta kommentit olisivat te­hok­kai­ta, on tärkeää pitää ne mah­dol­li­sim­man lyhyinä. Samalla niiden tulisi kuitenkin antaa lu­ki­joil­le riit­tä­väs­ti tietoa. Ongelmien rat­kai­se­mi­ses­sa hyvin muo­toil­lut kommentit ovat olen­nai­sen tärkeitä.

Java-kom­ment­te­ja on kolmea eri tyyppiä: yk­si­ri­vi­set kommentit, loh­ko­kom­men­tit (mo­ni­ri­vi­set kommentit) ja do­ku­men­taa­tio­kom­men­tit. Kaikki kommentit merkitään erikseen, jotta niitä ei oteta huomioon kään­tä­mi­sen yh­tey­des­sä. Seu­raa­vis­sa osioissa näytämme, miten Java-kom­ment­te­ja luodaan ja milloin kutakin tyyppiä käytetään.

Mitä kom­ment­ti­tyyp­pe­jä Java-kielessä on?

Riippuen siitä, millaista tietoa haluat kir­joit­taa, Java tarjoaa kolme erilaista kom­ment­ti­tyyp­piä. Nämä ovat:

Yhden rivin kommentit

Tämä on yk­sin­ker­tai­sin kom­ment­ti­vaih­toeh­to. Tä­män­tyyp­pi­nen kommentti luodaan kahdella pe­räk­käi­sel­lä kaut­ta­vii­val­la (//) ja se voi olla enintään yhden rivin pituinen. Yk­si­ri­vi­sis­sä kom­men­teis­sa ei tarvitse merkitä lop­pu­pis­tet­tä, koska se saa­vu­te­taan au­to­maat­ti­ses­ti rivin lopussa. Tä­män­tyyp­pi­set Java-kommentit sopivat lyhyille kom­men­teil­le, jotka se­lit­tä­vät toiminnon muu­ta­mal­la sanalla.

Mo­ni­ri­vi­set kommentit

Jos se­li­tyk­se­si on hieman pidempi, voit käyttää mo­ni­ri­vi­siä kom­ment­te­ja. Teoriassa ne voivat olla minkä pituisia tahansa. Ne sopivat vaih­toeh­tois­ten koo­di­ri­vien li­sää­mi­seen, jotka jätetään pois kään­tä­mi­ses­tä, tai yk­si­tyis­koh­tais­ten se­li­tys­ten li­sää­mi­seen. Mo­ni­ri­vi­set kommentit aloi­te­taan kaut­ta­vii­val­la ja tähdellä (/*). Kun kommentti päättyy, kirjoita vain tähti ja kaut­ta­vii­va (*/). Aloi­tus­kaut­ta­vii­van ja lo­pe­tus­kaut­ta­vii­van välinen teksti kä­si­tel­lään kom­ment­ti­na, eikä sitä oteta huomioon koodia kom­pi­loi­taes­sa.

Do­ku­men­taa­tion kommentit

Vaikka yk­si­ri­vi­set ja mo­ni­ri­vi­set kommentit voidaan teoriassa lisätä mihin tahansa läh­de­koo­diin, do­ku­men­taa­tio­kom­men­tit si­joi­te­taan aina suoraan niiden luokkien tai me­ne­tel­mien eteen, joita ne kuvaavat. Työ­ka­lu­jen avulla nämä kommentit luetaan ja tii­vis­te­tään HTML-do­ku­men­taa­tioon. Niitä käytetään pää­asias­sa me­ta­tie­to­jen luomiseen te­ki­jöil­le ja tie­tyn­tyyp­pi­sil­le pa­ra­met­reil­le. Ne merkitään @-sym­bo­lil­la. Do­ku­men­taa­tio­kom­men­tit aloi­te­taan kaut­ta­vii­val­la ja kahdella tähdellä (/**) ja lo­pe­te­taan tähdellä ja kaut­ta­vii­val­la (*/).

Yhden rivin kommentit

Jotta ym­mär­täi­sim­me, miten Java-kommentit toimivat käy­tän­nös­sä, tar­kas­te­lem­me muutamia yk­sin­ker­tai­sia esi­merk­ke­jä. Voit kokeilla näitä itse ja testata tulosta. Yk­si­ri­vi­nen kommentti alkaa kahdella kaut­ta­vii­val­la ja voi olla joko omalla rivillään tai si­joi­tet­tu ohjeiden jälkeen. **. Näin kommentti näyttää omalla rivillään:

// 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.");
	}
}

Jos käytät Java-komentoa System.out.println, vain lause “Tämä on lopussa tu­los­tet­ta­va teksti” näkyy. Kaksi kom­ment­tia näkyvät vain läh­de­koo­dis­sa.

Vaih­toeh­toi­ses­ti voit sijoittaa kommentin suoraan komennon jälkeen:

// 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.
	}
}

Kommentin sijainti ei muuta tu­los­tet­ta.

Mo­ni­ri­vi­set kommentit

Jos haluat lisätä mo­ni­ri­vi­sen kommentin koodiisi, voit lisätä sen koodin ohjeiden eteen tai jälkeen. Mo­ni­ri­vi­set kommentit aloi­te­taan aina kaut­ta­vii­val­la ja tähdellä. Tässä on mo­ni­ri­vi­nen kommentti ennen koodin ohjeita:

/* 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.");
	}
}

Tulostus on ”Tämä on teksti, joka tu­los­te­taan lopussa.”.

Näin lisäät kommentin ohjeiden alle:

// 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. */
	}
}

Tuloksen pitäisi olla sama kuin edel­li­ses­sä esi­mer­kis­sä. Koodin en­sim­mäi­sel­lä rivillä oleva yk­si­ri­vi­nen kommentti ei myöskään tule tu­los­te­tuk­si. Voit sijoittaa tähden ja kaut­ta­vii­van suoraan kommentin jälkeen tai käyttää erillistä riviä.

Do­ku­men­taa­tion kommentit

Do­ku­men­taa­tio­kom­men­tit toimivat samalla tavalla kuin loh­ko­kom­men­tit, mutta ne aloi­te­taan kaut­ta­vii­val­la ja kahdella tähdellä. Näin do­ku­men­taa­tio­työ­ka­lut voivat käyttää kom­ment­te­ja do­ku­men­taa­tion luomiseen. Tar­vit­taes­sa ne voivat sisältää myös HTML-tun­nis­tei­ta, kuten <h1>, <p> tai <strong>.

Javadoc, suosittu työkalu, jota voit käyttää do­ku­men­taa­tio­kom­ment­tien lu­ke­mi­seen, käyttää myös muita hyö­dyl­li­siä tun­nis­tei­ta. Tässä on joitakin tär­keim­piä niistä:

8ca68e1aa72a207c63996d6d46b7bc53