Komentar Java: Satu Baris, Banyak Baris, dan Javadoc

Untuk Apa Komentar Itu

Komentar adalah teks di kode sumbermu yang sepenuhnya diabaikan oleh compiler Java. Komentar tidak pernah menjadi bagian dari program yang berjalan; ia ada semata-mata untuk manusia yang membaca kodenya. Kamu memakai komentar untuk menjelaskan kenapa sesuatu dikerjakan dengan cara tertentu, meninggalkan pengingat, atau menonaktifkan kode sementara tanpa menghapusnya.

Java punya tiga jenis komentar: satu baris (//), komentar blok banyak baris (/* */), dan komentar dokumentasi Javadoc (/** */). Tugas dasarnya sama, yaitu diabaikan saat kompilasi, tetapi masing-masing dipakai dalam situasi yang berbeda.

Komentar Satu Baris

Dua garis miring (//) memulai komentar yang berlanjut sampai akhir baris itu. Compiler melewati semua yang ada dari // sampai pergantian baris.

public class Main {
    public static void main(String[] args) {
        // Print a greeting to the console
        System.out.println("Hello, Java!");

        int score = 90; // a comment can also sit after code
        System.out.println(score);
    }
}

Perhatikan bahwa komentar kedua berbagi baris dengan kode sungguhan. Semua yang ada sebelum // tetap dijalankan; hanya bagian setelahnya yang diabaikan. Ini gaya komentar yang paling umum untuk catatan singkat.

Komentar Blok Banyak Baris

Kalau catatanmu mencakup beberapa baris, komentar blok lebih rapi daripada menambahkan // di depan setiap baris. Komentar blok dimulai dengan /* dan diakhiri dengan */. Semua yang ada di antara keduanya, berapa pun jumlah barisnya, diabaikan.

public class Main {
    public static void main(String[] args) {
        /*
         * This program shows a block comment.
         * The leading asterisks on each line are just a
         * convention for readability - they are not required.
         */
        System.out.println("Block comments are handy.");
    }
}

Deretan karakter * yang sejajar di sisi kiri adalah konvensi gaya, bukan aturan. Bagian yang benar-benar penting hanyalah pembuka /* dan penutup */.

Menonaktifkan Kode dengan Komentar

Komentar adalah cara standar untuk menonaktifkan kode saat kamu bereksperimen, tanpa menghapusnya. Pakai // untuk satu baris, atau komentar blok untuk mematikan beberapa baris sekaligus.

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

Jalankan, dan kamu hanya akan melihat dua baris "runs" yang tercetak. Pemanggilan println yang dijadikan komentar tidak terlihat oleh compiler.

Jebakan yang umum: komentar blok tidak bisa disarangkan. */ pertama menutup komentar, tidak peduli berapa banyak /* yang ada sebelumnya. Jadi kamu tidak bisa membungkus blok /* ... */ di dalam blok /* ... */ lain: */ bagian dalam mengakhiri seluruh komentar dan sisanya menjadi syntax error. Kalau kamu perlu menonaktifkan bagian kode yang sudah berisi komentar blok, pakai // di setiap baris (sebagian besar editor bisa melakukannya dengan satu shortcut keyboard).

Komentar Dokumentasi Javadoc

Komentar Javadoc terlihat seperti komentar blok, tetapi dimulai dengan /**, yaitu dua tanda bintang. Komentar ini dimaksudkan untuk mendokumentasikan class, method, atau field, dan diletakkan tepat di atas hal yang dijelaskannya. Tool javadoc mengubahnya menjadi dokumentasi API berbentuk HTML yang bisa dijelajahi, dan IDE menampilkannya sebagai tooltip saat kursor diarahkan.

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));
    }
}

Tag @param, @return, dan @throws adalah field terstruktur yang dipahami oleh tool-nya. Bagi compiler, ini tetap hanya komentar yang diabaikan. Nilainya sepenuhnya ada pada dokumentasi yang dihasilkan dan petunjuk IDE yang diberikannya kepada developer lain (dan kepada dirimu sendiri, enam bulan kemudian).

Komentar yang Baik vs. Sekadar Ramai

Komentar seharusnya menjelaskan sesuatu yang tidak bisa disampaikan oleh kode itu sendiri. Komentar yang hanya mengulang isi kode menambah kesemrawutan dan cenderung jadi usang saat kodenya berubah.

// Bad: just repeats what the code obviously does
int i = i + 1; // add one to i

// Better: explains the reason, which the code can't show
retries++; // back off and retry; the API is rate-limited at 5 req/sec

Usahakan kode-mu mudah dibaca lewat nama dan struktur yang jelas, dan simpan komentar untuk kenapa-nya: maksud, pertimbangan, kasus tepi, dan tautan ke konteks. Kalau kamu mendapati dirimu menulis komentar untuk menjelaskan baris yang membingungkan, itu sering menjadi tanda bahwa sebaiknya kamu mengganti nama variabel atau memindahkan kodenya ke method tersendiri.

Berikutnya: Variabel

Sekarang kamu sudah bisa memberi catatan pada kodemu. Blok bangunan berikutnya adalah menyimpan data di dalamnya. Halaman berikutnya membahas variabel: cara mendeklarasikannya, tipe yang disimpannya, dan aturan yang diterapkan Java karena Java bertipe statis.