Komentar dan Documentation Comments

Kode yang baik sebagian besar menjelaskan dirinya sendiri lewat nama variabel dan method yang bermakna. Namun ada hal yang tidak tampak dari kode: alasan di balik keputusan, rumus yang dipakai, atau batasan yang harus dijaga. Untuk itu Java menyediakan tiga bentuk komentar — komentar baris, komentar blok, dan documentation comment — yang semuanya diabaikan compiler. Pada Chapter ini kita memakai ketiganya dalam satu program, lalu menghasilkan dokumentasi HTML otomatis dengan tool javadoc.

Tiga Jenis Komentar #

Java mengenal tiga bentuk komentar dengan peran berbeda:

Ketiganya diabaikan compiler javac — isi komentar tidak memengaruhi bytecode maupun hasil eksekusi program. Perbedaannya terletak pada pembacanya: dua bentuk pertama untuk pemrogram yang membaca kode, sedangkan documentation comment juga dibaca mesin untuk menghasilkan halaman dokumentasi.

Komentar di Dalam Program yang Berjalan #

Program berikut menghitung harga akhir setelah potongan harga, dengan ketiga jenis komentar di tempat yang sesuai:

/**
 * KalkulatorDiskon menghitung harga akhir setelah potongan harga.
 * Program latihan untuk Chapter Komentar dan Documentation Comments.
 */
public class KalkulatorDiskon {

    // Harga barang dalam Rupiah
    private static final int HARGA_ASLI = 250000;

    // Besar potongan dalam persen (0-100)
    private static final int PERSEN_DISKON = 20;

    public static void main(String[] args) {
        /*
         * Rumus: harga akhir = harga asli - (harga asli * diskon / 100).
         * Perkalian dilakukan lebih dulu agar urutan operasi benar.
         */
        int potongan = HARGA_ASLI * PERSEN_DISKON / 100;
        int hargaAkhir = HARGA_ASLI - potongan;

        System.out.println("Harga asli : Rp" + HARGA_ASLI);
        System.out.println("Diskon     : " + PERSEN_DISKON + "%");
        System.out.println("Harga akhir: Rp" + hargaAkhir);
    }
}

Output yang Dihasilkan:

Harga asli : Rp250000
Diskon     : 20%
Harga akhir: Rp200000

Mari kita bedah penempatan komentarnya:

1. Baris 1-4 (/** ... */): documentation comment milik class — ditulis tepat di atas deklarasi public class KalkulatorDiskon sehingga javadoc mengaitkannya dengan class ini.
2. Baris 7 dan 10 (// ...): komentar baris yang menempel pada konstanta. Komentar baris paling sering dipakai untuk catatan singkat di sebelah satu statement atau deklarasi.
3. Baris 15-18 (/* ... */): komentar blok yang menjelaskan rumus perhitungan di dalam method. Tanda * di tiap baris hanyalah gaya penulisan agar mudah dibaca, bukan syarat sintaks.
4. Baris 19-20 (int potongan = ...): kode di bawah komentar blok tetap dikompilasi normal — komentar tidak mengubah perilaku sama sekali, seperti terlihat pada output di atas.

Documentation Comments dan javadoc #

Documentation comment adalah komentar blok khusus yang diawali dua tanda bintang. Di dalamnya kita dapat memakai tag berlabel untuk menjelaskan parameter, nilai balik, dan kondisi error. Contoh berikut mendokumentasikan sebuah method penghitung harga:

/**
 * Menghitung harga akhir setelah potongan harga diterapkan.
 *
 * @param hargaAsli    harga sebelum potongan, dalam Rupiah
 * @param persenDiskon besar potongan dalam persen (0-100)
 * @return harga setelah potongan harga diterapkan
 */
public static int hitungHargaAkhir(int hargaAsli, int persenDiskon) {
    return hargaAsli - hargaAsli * persenDiskon / 100;
}

Tag yang paling sering dipakai adalah @param untuk setiap parameter, @return untuk nilai balik, serta @throws untuk kondisi error yang mungkin terjadi. Tool javadoc membaca seluruh documentation comment dalam berkas sumber dan menghasilkan dokumentasi HTML. Jalankan perintah berikut dari direktori berkas sumbernya:

javadoc -d doc KalkulatorDiskon.java

Perintah tersebut membuat direktori doc berisi halaman HTML — di antaranya index.html sebagai halaman utama dan KalkulatorDiskon.html untuk class tersebut. Buka index.html di browser dan Anda akan melihat dokumentasi berformat rapi, lengkap dengan daftar method dan penjelasan parameternya. Inilah cara pustaka standar Java mendokumentasikan diri; halaman API di docs.oracle.com dihasilkan dari documentation comment yang sama.

Kapan dan Apa yang Dikomentari #

Komentar yang berkualitas menjelaskan mengapa, bukan mengulang apa. Baris int total = harga * jumlah; tidak butuh komentar “kalikan harga dengan jumlah” karena kode sudah menyatakannya. Sebaliknya, komentar seperti “diskon dihitung dari harga setelah pajak, sesuai kebijakan per 2025” menyimpan informasi yang tidak ada di dalam kode.

Beberapa pedoman praktis untuk kita terapkan:

• Jelaskan rumus, batasan, dan keputusan yang tidak terlihat dari kode.
• Perbarui atau hapus komentar yang sudah tidak sesuai dengan kodenya.
• Utamakan mengganti komentar penjelasan dengan nama variabel dan method yang lebih bermakna.

Komentar melengkapi kode dengan penjelasan tanpa mengubah perilaku program. Unsur berikutnya yang membentuk perilaku adalah pasangan statement dan expression: instruksi yang melakukan aksi dan potongan kode yang menghasilkan nilai. Chapter berikutnya membedah keduanya sampai ke aturan evaluasinya.

Referensi #

• Oracle: Learning the Java Language
• Oracle JDK 25 Documentation

/**
 * KalkulatorDiskon menghitung harga akhir setelah potongan harga.
 * Program latihan untuk Chapter Komentar dan Documentation Comments.
 */
public class KalkulatorDiskon {

    // Harga barang dalam Rupiah
    private static final int HARGA_ASLI = 250000;

    // Besar potongan dalam persen (0-100)
    private static final int PERSEN_DISKON = 20;

    public static void main(String[] args) {
        /*
         * Rumus: harga akhir = harga asli - (harga asli * diskon / 100).
         * Perkalian dilakukan lebih dulu agar urutan operasi benar.
         */
        int potongan = HARGA_ASLI * PERSEN_DISKON / 100;
        int hargaAkhir = HARGA_ASLI - potongan;

        System.out.println("Harga asli : Rp" + HARGA_ASLI);
        System.out.println("Diskon     : " + PERSEN_DISKON + "%");
        System.out.println("Harga akhir: Rp" + hargaAkhir);
    }
}