Komentarze w kodzie Java: jednolinijkowe, blokowe, Javadoc i Markdown od JDK 23

Komentarze w kodzie to fragmenty tekstu, które kompilator Javy całkowicie pomija, a które czyta człowiek: Wy za pół roku, osoba z Waszego zespołu albo narzędzie javadoc, które robi z nich dokumentację HTML. Java ma trzy klasyczne rodzaje komentarzy: jednolinijkowe //, blokowe /* */ i dokumentujące /** */, a od JDK 23 doszły komentarze dokumentujące w Markdownie, zaczynane od ///. Ta lekcja pokazuje wszystkie cztery na jednym działającym przykładzie, trzy błędy kompilatora, które komentarz potrafi wywołać, i zasady komentowania testów automatycznych, bo w testach komentarz częściej szkodzi, niż pomaga.

To piąta lekcja kursu Javy dla testerów na blogu Quality Island. Wcześniej napisaliście pierwszy program w Javie, a po tej lekcji przejdziecie do typów danych w Javie. Film poniżej pokazuje temat na ekranie IntelliJ IDEA, tekst pod nim rozwija go o rzeczy, których w filmie nie ma: Markdown w Javadoc, komunikaty kompilatora i komentarze w testach JUnit.

Jakie rodzaje komentarzy w kodzie ma Java?

Java rozróżnia komentarze po pierwszych znakach. Kompilator javac traktuje każdy z nich jak białą spację, więc żaden komentarz nie zmienia działania programu ani jego szybkości. Różnią się tym, kto je czyta: komentarze // i /* */ są wyłącznie dla ludzi czytających kod, a komentarze dokumentujące czyta dodatkowo narzędzie javadoc i środowisko programistyczne, które pokazuje je w podpowiedziach po najechaniu na nazwę metody.

Wszystkie cztery rodzaje widać w jednej klasie poniżej. To prosty kalkulator rabatu ze sklepu testowego: liczy cenę w groszach, żeby uniknąć błędów zaokrągleń, o których więcej powiemy w następnej lekcji. Kod skompilowaliśmy i uruchomiliśmy 11.10.2026 na OpenJDK 25.0.2 z opcją --release 25, czyli tak, jak buduje go projekt Maven z lekcji 3.

package pl.qi;

/**
 * Liczy cenę po rabacie dla koszyka w sklepie testowym.
 * <p>
 * Klasa jest celowo mała: służy jako przykład komentarzy dokumentujących.
 *
 * @author Quality Island
 * @since 1.0
 */
public class Rabat {

    /** Najwyższy rabat procentowy, jaki przyjmuje sklep. */
    public static final int MAKS_RABAT = 50;

    /**
     * Zwraca cenę po rabacie, zaokrągloną w dół do pełnych groszy.
     *
     * @param cenaWGroszach cena przed rabatem, w groszach, nie mniejsza niż 0
     * @param procent       rabat w procentach, od 0 do {@value #MAKS_RABAT}
     * @return cena po rabacie w groszach
     * @throws IllegalArgumentException gdy procent jest poza zakresem
     * @see <a href="https://qualityisland.pl/typy-danych-w-javie/">Typy danych w Javie</a>
     */
    public static long poRabacie(long cenaWGroszach, int procent) {
        if (procent < 0 || procent > MAKS_RABAT) {
            throw new IllegalArgumentException("Rabat poza zakresem: " + procent);
        }
        // Liczymy w groszach, bo double gubi grosze (szczegóły w lekcji o typach danych)
        return cenaWGroszach * (100 - procent) / 100;
    }

    /*
     * Wersja z zaokrągleniem do góry była w sprincie 14,
     * ale dział finansów wybrał zaokrąglenie w dół (zgłoszenie SKLEP-482).
     */

    /// Zwraca **true**, gdy rabat da się zastosować.
    ///
    /// Komentarz w składni Markdown (JEP 467, od JDK 23):
    /// - `procent` musi być w zakresie od 0 do [#MAKS_RABAT]
    /// - metoda nie rzuca wyjątków
    ///
    /// @param procent rabat w procentach
    /// @return `true` dla poprawnego rabatu
    public static boolean czyPoprawny(int procent) {
        return procent >= 0 && procent <= MAKS_RABAT;
    }

    public static void main(String[] args) {
        System.out.println(poRabacie(19_999, 15)); // 199,99 zł minus 15%
        System.out.println(czyPoprawny(60));
    }
}

$ javac -d out src/pl/qi/Rabat.java
$ java -cp out pl.qi.Rabat
16999
false

Jak działa komentarz jednolinijkowy i blokowy?

Komentarz jednolinijkowy zaczyna się od // i kończy razem z linią. Może stać w osobnej linii albo na końcu instrukcji, jak w przykładzie z rabatem. Komentarz blokowy zaczyna się od /*, kończy na */ i może obejmować dowolnie wiele linii. Gwiazdki na początku kolejnych linii są tylko konwencją, kompilator ich nie wymaga.

Według specyfikacji języka Java (JLS, rozdział 3.7, wydanie dla Java SE 25 z 2025 roku) komentarze się nie zagnieżdżają, a znaki /* i */ nie mają żadnego znaczenia wewnątrz komentarza zaczętego od //. Z tej jednej reguły wynikają dwa błędy opisane niżej w sekcji o kompilatorze. W IntelliJ IDEA nie musicie wpisywać znaków ręcznie: skrót Ctrl+/ (na macOS Cmd+/) komentuje lub odkomentowuje zaznaczone linie komentarzem jednolinijkowym, a Ctrl+Shift+/ (Cmd+Option+/) otacza zaznaczenie komentarzem blokowym. Środowisko poznaliście w lekcji IntelliJ IDEA: pierwszy projekt.

Najważniejsza zasada nie dotyczy składni, tylko treści. Dobry komentarz mówi, dlaczego kod wygląda tak, a nie inaczej; to, co kod robi, powinno wynikać z nazw zmiennych i metod. Komentarz // zwiększ licznik o 1 nad linią licznik++ nie wnosi nic. Komentarz // zaokrąglamy w dół, bo tak liczy system księgowy (SKLEP-482) ratuje kolejną osobę przed „naprawieniem” poprawnego kodu. Podobnie widzimy w projektach testowych: więcej kłopotu niż brakujące komentarze sprawiają nieaktualne, które mówią co innego niż kod. Jeśli Wasz zespół zmienia logikę, niech zmienia też komentarz w tym samym commicie, a przegląd kodu niech to sprawdza; to Wam oszczędzi najwięcej czasu.

Czym jest Javadoc i jakie tagi warto znać?

Javadoc to komentarz dokumentujący /** */ umieszczony bezpośrednio przed klasą, polem, konstruktorem albo metodą. Pierwsze zdanie trafia do podsumowania w wygenerowanej dokumentacji, reszta do opisu szczegółowego. Po opisie stoją tagi blokowe zaczynane od @, a w tekście można używać tagów wewnętrznych w nawiasach klamrowych. Specyfikacja komentarzy dokumentujących Oracle dla Java SE 25 (2025) opisuje 27 tagów; w codziennej pracy testera wystarczy kilka z tabeli.

Dokumentację HTML generuje narzędzie javadoc, które instaluje się razem z JDK. Wystarczy wskazać katalog ze źródłami i pakiet. Przy okazji javadoc sprawdza komentarze i ostrzega o brakach, co jest całkiem dobrym, darmowym przeglądem dokumentacji:

$ javadoc -d doc -sourcepath src pl.qi
src/pl/qi/Rabat.java:11: warning: use of default constructor, which does not provide a comment
public class Rabat {
       ^
src/pl/qi/Rabat.java:50: warning: no comment
    public static void main(String[] args) {
                       ^
2 warnings

Oba ostrzeżenia są uczciwe: klasa ma domyślny konstruktor bez opisu, a metoda main nie ma komentarza. W katalogu doc powstaje strona pl/qi/Rabat.html z opisem obu metod, tabelą parametrów i wartością stałej 50 wstawioną w miejsce tagu {@value}. W projekcie Maven to samo robi polecenie mvn javadoc:javadoc.

Jak pisać Javadoc w Markdownie od JDK 23?

Według JEP 467 „Markdown Documentation Comments”, dostarczonego w JDK 23, komentarz dokumentujący może składać się z linii zaczynanych od trzech ukośników ///, a jego treść jest pisana w Markdownie (CommonMark) zamiast w HTML. Pogrubienie piszecie jako **tekst**, kod jako `kod`, listy myślnikami na początku linii, a odnośnik do elementu API w nawiasach kwadratowych, np. [#MAKS_RABAT]. Tagi blokowe @param i @return działają jak wcześniej.

Metoda czyPoprawny w klasie Rabat ma właśnie taki komentarz. Po wygenerowaniu dokumentacji narzędziem javadoc z JDK 25 słowo **true** zamieniło się w znacznik <strong>, a nazwy w odwrotnych apostrofach w <code>, czyli Markdown został przetworzony tak, jak obiecuje JEP.

Jest jedna pułapka. Dla kompilatora /// to zwykły komentarz jednolinijkowy, więc klasa z takim komentarzem skompiluje się także na Javie 21 i starszej. Markdown zinterpretuje jednak dopiero javadoc w wersji 23 lub nowszej. Jeśli Wasz projekt budujecie na Javie 21, a dokumentację generujecie tym samym JDK, komentarze /// po prostu znikną z dokumentacji. W takim projekcie zostańcie przy /** */; po przejściu na Javę 25 możecie przechodzić na Markdown stopniowo, bo oba style mogą żyć w jednym pliku.

Jakie błędy kompilatora powodują komentarze w kodzie?

Komentarz wydaje się najbezpieczniejszym miejscem w pliku, a jednak potrafi zatrzymać kompilację. Wszystkie trzy błędy z tabeli wywołaliśmy celowo i przepisaliśmy komunikaty z javac 25 uruchomionego z angielskimi komunikatami, bo takie zobaczycie w większości pipeline’ów CI.

Trzeci błąd wydaje się absurdalny, dopóki nie zobaczycie, skąd się bierze. Według JLS (rozdział 3.3) kompilator zamienia sekwencje Unicode \uXXXX na znaki, zanim w ogóle zacznie szukać komentarzy. Ścieżka C:\users zawiera \u, po którym nie stoją cztery cyfry szesnastkowe, więc kompilator zgłasza błąd w linii, która „przecież jest komentarzem”.

public class Unicode {
    public static void main(String[] args) {
        boolean wylaczony = true;
        // \u000d wylaczony = false;
        System.out.println("Test wyłączony: " + wylaczony);
    }
}

$ javac Unicode.java && java Unicode
Test wyłączony: false

Jak komentować testy automatyczne w Javie?

W testach automatycznych komentarz ma trudniejsze zadanie niż w kodzie produkcyjnym. Test jest jednocześnie kodem i specyfikacją zachowania systemu, więc jego treść powinna dać się przeczytać bez komentarzy. W naszej praktyce na przeglądach repozytoriów testów najczęściej poprawiamy dwa rodzaje komentarzy: zakomentowane całe testy i komentarze, które powtarzają nazwę metody. Zamiast nich JUnit daje dwa lepsze narzędzia: adnotację @DisplayName, która trafia do raportu, i @Disabled z powodem, który raport pokaże przy pominiętym teście.

package pl.qi;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;

import org.junit.jupiter.api.Disabled;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;

class RabatTest {

    @Test
    @DisplayName("Rabat 15% od 199,99 zł daje 169,99 zł")
    void rabatZaokraglaWDol() {
        // Zaokrąglamy w dół, bo tak liczy system księgowy (SKLEP-482).
        // Bez tej informacji ktoś "naprawi" oczekiwane 16999 na 17000.
        long wynik = Rabat.poRabacie(19_999, 15);

        assertEquals(16_999, wynik);
    }

    @Test
    void rabatPowyzejLimituJestOdrzucany() {
        assertThrows(IllegalArgumentException.class, () -> Rabat.poRabacie(10_000, 51));
    }

    @Test
    @Disabled("SKLEP-517: rabat dla koszyka B2B jeszcze niewdrożony, włączyć po wydaniu 2.4")
    void rabatB2B() {
    }
}

RabatTest ✔
├─ Rabat 15% od 199,99 zł daje 169,99 zł ✔
├─ rabatB2B() ↷ SKLEP-517: rabat dla koszyka B2B jeszcze niewdrożony, włączyć po wydaniu 2.4
└─ rabatPowyzejLimituJestOdrzucany() ✔
3 tests found, 1 skipped, 2 successful, 0 failed

Test uruchomiliśmy w JUnit 6.1.3 (konsola JUnit Platform). Zwróćcie uwagę, że powód z @Disabled stoi w raporcie, a zakomentowanego testu raport w ogóle by nie pokazał: zniknąłby z liczby testów i nikt by o nim nie pamiętał. Komentarz w teście rabatZaokraglaWDol zostaje, bo wyjaśnia, dlaczego oczekiwany wynik to 16 999, a nie 17 000 groszy. Bez niego ktoś „naprawi” asercję przy pierwszym czerwonym przebiegu.

Ta sama zasada działa w testach UI. Komentarz przy Thread.sleep(2000) typu „czekamy na stronę” jest sygnałem problemu, nie dokumentacją: zamiast go opisywać, zamieńcie go na jawne oczekiwanie z lekcji o explicit wait i implicit wait w Selenium WebDriver. Szerzej o nawykach, które psują zestawy testów, piszemy na portalu Strefa QA w tekście o najczęstszych antywzorcach w testowaniu oprogramowania. Komentarz „nie ruszać, działa” to najkrótsza forma dokumentacji i jednocześnie najdłuższa forma długu technicznego.

Ćwiczenie: jak udokumentować metodę z testu wydajności?

Zadanie: napiszcie metodę wLimicie(long czasMs, long limitMs), która sprawdza, czy zmierzony czas odpowiedzi API mieści się w limicie z wymagań niefunkcjonalnych. Udokumentujcie ją komentarzem Javadoc z tagami @param, @return i @throws, dodajcie jeden komentarz „dlaczego” w treści metody i wygenerujcie dokumentację poleceniem javadoc. Spróbujcie samodzielnie, zanim zajrzycie do rozwiązania.

Rozwiązanie

public class Cwiczenie {

    /**
     * Sprawdza, czy czas odpowiedzi API mieści się w limicie z wymagań.
     *
     * @param czasMs    zmierzony czas odpowiedzi w milisekundach
     * @param limitMs   limit z wymagań niefunkcjonalnych, w milisekundach
     * @return {@code true}, gdy czas nie przekracza limitu
     * @throws IllegalArgumentException gdy któraś wartość jest ujemna
     */
    public static boolean wLimicie(long czasMs, long limitMs) {
        if (czasMs < 0 || limitMs < 0) {
            throw new IllegalArgumentException("Czas nie może być ujemny");
        }
        // Równy limitowi przechodzi: tak mówi wymaganie (limit włącznie)
        return czasMs <= limitMs;
    }

    public static void main(String[] args) {
        System.out.println(wLimicie(800, 800));
    }
}

Program wypisuje true, bo czas równy limitowi przechodzi. Właśnie to opisuje komentarz w treści metody: przy wymaganiu „czas odpowiedzi do 800 ms” ktoś mógłby napisać < zamiast <= i test graniczny dla dokładnie 800 ms zacząłby padać. Javadoc dla tego pliku wygenerował się z czterema ostrzeżeniami o brakujących opisach klasy, konstruktora domyślnego i metody main; dopiszcie je, a ostrzeżeń nie będzie.

Co dalej po lekcji o komentarzach?

Komentarze to najprostszy temat kursu, ale wracają w każdej kolejnej lekcji: od typów danych i operatorów matematycznych, przez funkcje, po klasy Page Object w testach Selenium. Jeśli wolicie przerobić podstawy Javy z trenerem, a nie z filmu, na szkoleniu Programowanie w języku Java dla testerów oprogramowania (2 dni, cena z karty szkolenia 2 212 zł netto, odczyt 10.10.2026) piszecie kod pod testy od pierwszego dnia. Dla osób, które zaczynają od zera, jest Wprowadzenie do programowania od podstaw w Javie, a kolejnym krokiem po podstawach jest kurs automatyzacji testów Selenium WebDriver.

Powiązane na blogu Quality Island

• Java: pierwszy program, lekcja 4 kursu
• Typy danych w Javie, lekcja 6 kursu
• Java dla testerów automatyzujących: plan nauki na 8 tygodni
• Asercje w testach automatycznych: Selenium, JUnit, TestNG
• Książki do nauki Javy dla testerów

Pełna lista źródeł

• Oracle, The Java Language Specification, Java SE 25, rozdział 3 (3.3 Unicode Escapes, 3.7 Comments), 2025.
• OpenJDK, JEP 467: Markdown Documentation Comments, wydanie JDK 23, 2024.
• Oracle, Documentation Comment Specification for the Standard Doclet, Java SE 25, 2025.
• Oracle, The javadoc Command, Java SE 25, 2025.
• Oracle, Using Markdown in Documentation Comments, Java SE 23, 2024.
• Oracle, Oracle Java SE Support Roadmap, odczyt 10.10.2026.
• Google, Google Java Style Guide, rozdział 7 Javadoc, odczyt 2026.
• JUnit, JUnit User Guide (DisplayName, Disabled), odczyt 2026.
• Quality Island, uruchomienie przykładów z tej lekcji na OpenJDK 25.0.2 (opcja --release 25) i JUnit 6.1.3, 11.10.2026.