Komentarze w Javie: jednoliniowe, wieloliniowe i Javadoc

Do czego służą komentarze

Komentarz to tekst w kodzie źródłowym, który kompilator Javy całkowicie ignoruje. Nigdy nie staje się częścią działającego programu: istnieje wyłącznie dla ludzi, którzy czytają kod. Komentarzy używasz, aby wyjaśnić, dlaczego coś zrobiono w określony sposób, zostawić przypomnienia albo tymczasowo wyłączyć kod bez usuwania go.

Java ma trzy rodzaje komentarzy: jednoliniowe (//), wieloliniowe komentarze blokowe (/* */) i komentarze dokumentacyjne Javadoc (/** */). Wszystkie robią to samo, czyli są ignorowane podczas kompilacji, ale każdy sprawdza się w innych sytuacjach.

Komentarze jednoliniowe

Dwa ukośniki (//) rozpoczynają komentarz, który trwa do końca bieżącego wiersza. Kompilator pomija wszystko od // do końca wiersza.

public class Main {
    public static void main(String[] args) {
        // Wypisuje powitanie w konsoli
        System.out.println("Hello, Java!");

        int score = 90; // komentarz może też stać po kodzie
        System.out.println(score);
    }
}

Zauważ, że drugi komentarz dzieli wiersz z prawdziwym kodem. Wszystko przed // nadal się wykonuje, ignorowana jest tylko część po nim. To najczęstszy styl komentarzy do krótkich notatek.

Wieloliniowe komentarze blokowe

Gdy notatka zajmuje kilka wierszy, komentarz blokowy jest czytelniejszy niż dodawanie // na początku każdego wiersza. Komentarz blokowy zaczyna się od /* i kończy na */. Wszystko pomiędzy, niezależnie od liczby wierszy, jest ignorowane.

public class Main {
    public static void main(String[] args) {
        /*
         * Ten program pokazuje komentarz blokowy.
         * Gwiazdki na początku każdego wiersza to tylko
         * konwencja poprawiająca czytelność: nie są wymagane.
         */
        System.out.println("Block comments are handy.");
    }
}

Wyrównane znaki * na początku wierszy to konwencja stylu, a nie reguła. Naprawdę liczą się tylko otwierające /* i zamykające */.

Zakomentowanie kodu

Komentarze to standardowy sposób na wyłączenie kodu podczas eksperymentów bez usuwania go. Użyj // dla jednego wiersza albo komentarza blokowego, aby wyłączyć kilka wierszy naraz.

public class Main {
    public static void main(String[] args) {
        System.out.println("This line runs.");

        // System.out.println("This line is disabled.");

        /*
        System.out.println("So is this one,");
        System.out.println("and this one too.");
        */

        System.out.println("This line runs as well.");
    }
}

Uruchom program, a zobaczysz tylko dwa wiersze z „runs”. Zakomentowane wywołania println są dla kompilatora niewidoczne.

Częsta pułapka: komentarze blokowe nie mogą być zagnieżdżone. Pierwsze */ zamyka komentarz, bez względu na to, ile /* było przed nim. Nie możesz więc umieścić bloku /* ... */ wewnątrz innego bloku /* ... */: wewnętrzne */ kończy całość, a reszta staje się błędem składni. Jeśli musisz wyłączyć fragment, który już zawiera komentarze blokowe, użyj // w każdym wierszu (większość edytorów robi to jednym skrótem klawiszowym).

Komentarze dokumentacyjne Javadoc

Komentarz Javadoc wygląda jak komentarz blokowy, ale zaczyna się od /**, czyli dwóch gwiazdek. Służy do dokumentowania klasy, metody lub pola i stoi bezpośrednio nad elementem, który opisuje. Narzędzie javadoc zamienia takie komentarze w przeglądalną dokumentację API w HTML, a środowiska IDE pokazują je w podpowiedziach po najechaniu kursorem.

public class Main {
    /**
     * Returns the larger of two integers.
     *
     * @param a the first number
     * @param b the second number
     * @return whichever of {@code a} and {@code b} is greater
     */
    static int max(int a, int b) {
        return a > b ? a : b;
    }

    public static void main(String[] args) {
        System.out.println(max(3, 9));
    }
}

Znaczniki @param, @return i @throws to ustrukturyzowane pola, które rozumieją narzędzia. Dla kompilatora to nadal zwykły ignorowany komentarz: cała wartość tkwi w dokumentacji, którą generuje, i podpowiedziach w IDE dla innych programistów (i dla ciebie za pół roku).

Dobre komentarze a szum

Komentarz powinien wyjaśniać coś, czego kod nie powie sam. Komentarze, które tylko powtarzają kod, zaśmiecają go i z czasem przestają pasować, gdy kod się zmienia.

// Źle: tylko powtarza to, co kod oczywiście robi
int i = i + 1; // dodaje jeden do i

// Lepiej: wyjaśnia powód, którego kod nie pokaże
retries++; // odczekaj i spróbuj ponownie; API ma limit 5 zapytań/s

Staraj się, by kod był czytelny dzięki jasnym nazwom i strukturze, a komentarze zostaw na dlaczego: intencje, kompromisy, przypadki brzegowe i odnośniki do kontekstu. Jeśli piszesz komentarz, aby wyjaśnić zagmatwany wiersz, często jest to sygnał, że lepiej zmienić nazwę zmiennej albo wydzielić metodę.

Dalej: zmienne

Skoro potrafisz już opisywać kod, kolejnym elementem jest przechowywanie w nim danych. Następna strona omawia zmienne: jak je deklarować, jakie typy przechowują i jakie zasady narzuca Java, bo jest językiem statycznie typowanym.