Javadoc dan Kode Bersih

Kode yang bersih dibaca dua kali lebih sering daripada ditulis sekali, sehingga dokumentasi, penamaan, dan gaya yang konsisten bukan hiasan, melainkan bagian dari kerja teknisnya. Topik ini membahas Javadoc untuk mendokumentasikan kode Java, kebiasaan penamaan yang mengurangi pertanyaan, penyatuan gaya lewat alat, dan etika code review. Semuanya dipraktikkan pada kode kecil yang tetap bisa dijalankan, karena aturan kebersihan kode paling mudah dinilai pada contoh sungguhan.

Javadoc: kontrak yang menggantung di atas kode#

Javadoc adalah format komentar khusus yang diawali /** dan ditempatkan tepat di atas deklarasi kelas, metode, atau field. Perbedaannya dengan komentar biasa terletak pada siapa yang membacanya, karena komentar biasa ditujukan untuk pembaca kode, sedangkan Javadoc ditujukan untuk pemakai kode yang tidak harus membuka implementasinya. Alat javadoc yang tersedia di JDK mengolah komentar-komentar itu menjadi halaman HTML seperti halaman dokumentasi API Java yang biasa dirujuk.

Isi Javadoc yang berguna menjawab kontrak, bukan mengulang implementasi. Kalimat pertama merangkum perilaku dalam satu baris, tag @param menjelaskan tiap parameter beserta syaratnya, tag @return menjelaskan hasilnya, dan tag @throws menjelaskan exception yang bisa dilempar beserta kondisinya. Contoh lengkapnya terlihat pada berkas berikut, yang tetap dapat dijalankan karena komentar tidak mengubah perilaku apa pun.

/**
 * Konverter suhu untuk laporan percobaan laboratorium sederhana.
 */
public class KonverterSuhu {

    /**
     * Mengubah suhu Celsius menjadi Fahrenheit.
     *
     * @param celsius suhu dalam derajat Celsius, boleh negatif
     * @return suhu setara dalam derajat Fahrenheit
     */
    static double celsiusKeFahrenheit(double celsius) {
        return celsius * 9 / 5 + 32;
    }

    public static void main(String[] args) {
        System.out.printf("0 C  = %.1f F%n", celsiusKeFahrenheit(0));
        System.out.printf("37 C = %.1f F%n", celsiusKeFahrenheit(37));
    }
}

0 C  = 32.0 F
37 C = 98.6 F

Menghasilkan halaman dokumentasinya memakai perintah javadoc yang ikut terpasang bersama JDK, dan hasilnya berupa folder HTML siap dibuka di browser.

# tidak-dijalankan
# membuat dokumentasi HTML dari komentar Javadoc ke folder dok
javadoc -d dok KonverterSuhu.java

Menulis Javadoc yang berguna#

Dokumentasi yang berguna menjelaskan hal yang tidak terlihat dari tanda tangan metode, yaitu syarat, batas, dan akibat yang mungkin terjadi. Baris @param celsius boleh negatif memberi informasi yang tidak bisa ditebak dari nama parameter, dan @throws yang menyebut kondisi pemicunya menghemat waktu pembaca yang sedang menulis pemanggilan. Tag @code merender teks sebagai kode, sehingga nama kelas dan nilai literal tampil dengan jelas di HTML.

// tidak-dijalankan
/**
 * Menghitung rata-rata dari daftar nilai ujian.
 *
 * @param nilai daftar nilai yang tidak boleh kosong
 * @return rata-rata aritmetika dari seluruh nilainya
 * @throws IllegalArgumentException bila {@code nilai} kosong
 */
static double rataRata(List<Integer> nilai) { ... }

Ada juga hal yang tidak perlu didokumentasikan. Getter dan setter yang benar-benar sederhana cukup diberi kalimat satu baris atau bahkan tidak sama sekali, karena kalimat yang mengulang nama metode seperti “mengembalikan judul” pada metode getJudul() tidak menambah apa pun. Dokumentasi yang menyalin isi kode juga cepat basi, karena setiap perubahan implementasi menuntut dua tempat untuk diperbarui. Aturan praktisnya, dokumentasikan kontrak yang dipakai orang lain, dan sisakan komentar biasa untuk penjelasan lokal di dalam implementasi.

Penamaan yang mengurangi pertanyaan#

Nama adalah dokumentasi yang paling sering dibaca, sehingga penamaan yang baik mengurangi kebutuhan Javadoc itu sendiri. Konvensi Java yang berlaku luas sudah dibiasakan sejak topik Kelas dan Objek, dan tabel berikut merangkum kebiasaannya beserta contoh yang mengikuti.

Di luar kapitalisasi, dua kebiasaan berikut memberi dampak paling besar. Pertama, tulis nama yang menyatakan niat, karena durasiMenit lebih informatif daripada durasi, dan selisihHari lebih jujur daripada delta. Kedua, hindari singkatan yang tidak disepakati bersama, karena hrgTtl memaksa pembaca menerjemahkan ulang setiap kali ditemui. Nama yang panjang sedikit terbukti lebih murah daripada nama pendek yang samar.

Gaya menulis kode dan alat pemeriksa#

Gaya kode mencakup lebar indentasi, posisi kurung kurawal, panjang baris, dan urutan anggota kelas. Perdebatan soal selera jenis ini tidak pernah tuntas, dan justru karena itu penyelesaiannya bukan perdebatan, melainkan satu konfigurasi yang disepakati tim. Alat pemformat otomatis seperti google-java-format atau formatter bawaan IDE mengubah penataan tanpa mengubah perilaku, sehingga tidak ada lagi suntingan yang berantakan hanya karena dua orang memakai indentasi berbeda.

Pemeriksa gaya (linter) seperti Checkstyle menambah lapisan berikutnya, yaitu melanggar aturan yang tidak bisa diperbaiki formatter saja, misalnya panjang metode, jumlah parameter, atau urutan modifier. Keduanya biasanya dipasang sebagai plugin Maven, sehingga pemeriksaan berjalan otomatis pada build. Dengan pemeriksaan otomatis seperti ini, ulasan manusia pada code review bisa menyisihkan hal-hal mekanis dan menyisakan pertanyaan yang benar-benar butuh penilaian.

Kebiasaan code review#

Code review adalah proses membaca kode sebelum digabung, dan tujuan utamanya menjaga kualitas sekaligus menyebarkan pemahaman kode ke lebih dari satu orang. Review yang sehat dimulai dari perubahan kecil, karena ulasan atas tiga ratus baris baru berjalan dangkal, sedangkan lima puluh baris yang fokus bisa dibaca sungguh-sungguh. Pembuat perubahan membantu dengan menulis deskripsi yang menjelaskan kenapa perubahan itu diperlukan.

Komentar ulasan menyasar kode, bukan orangnya, dan menawarkan alternatif alih-alih sekadar menolak. Pertanyaan “kenapa batas ini 100” memicu percakapan yang lebih baik daripada “ini salah”, dan penilaian atas selera pribadi sebaiknya diserahkan ke alat yang sudah dikonfigurasi tim. Di sisi lain, pembuat perubahan menanggapi komentar dengan perbaikan atau penjelasan, dan ulasan dianggap tuntas ketika keduanya sepakat bahwa kode siap digabung.

Kebersihan yang dibicarakan sepanjang topik ini saling menopang di ruang review. Javadoc yang benar menghemat satu putaran pertanyaan. Penamaan yang jelas mengurangi komentar “ini untuk apa”, dan gaya yang diserahkan ke alat membebaskan perhatian untuk masalah yang sesungguhnya.

Kesalahan umum#

• Menulis Javadoc yang mengulang kode. Kalimat “mengembalikan nilai judul” pada getter getJudul() tidak menambah informasi apa pun. Dokumentasikan syarat, batas, dan efek yang tidak terlihat dari tanda tangan metode.
• Membiarkan dokumentasi basi. Javadoc yang tidak diikutkan saat perilaku berubah menjadi sumber informasi palsu yang lebih bahaya daripada tanpa dokumentasi. Perlakukan perubahan perilaku sebagai tugas dua tempat.
• Memperbaiki nama samar dengan menambah komentar. Komentar pada baris int d; // durasi dalam menit harus ditulis ulang di setiap pemakaian, sedangkan penamaan ulang menjadi durasiMenit memperbaiki semua tempat sekaligus.
• Mengulasi selera gaya secara manual. Komentar soal spasi dan indentasi memakan waktu ulasan tanpa nilai teknis. Serahkan pada formatter, dan tambahkan aturannya ke konfigurasi tim.
• Mengirim perubahan besar untuk direview. Reviewer yang menghadapi ratusan baris mengalah dengan menyetujui tanpa membaca. Pecah pekerjaan menjadi beberapa perubahan kecil yang masing-masing utuh.

Ringkasan#

• Javadoc adalah komentar /** ... */ di atas deklarasi yang diolah alat javadoc menjadi HTML, berisi kontrak metode lewat @param, @return, dan @throws.
• Dokumentasi yang berguna menyatakan syarat dan akibat yang tidak terlihat dari tanda tangan metode, bukan mengulang isi kodenya.
• Penamaan yang menyatakan niat mengurangi kebutuhan komentar, dan gaya diserahkan ke formatter serta linter yang dikonfigurasi bersama tim.
• Code review bekerja paling baik pada perubahan kecil dengan komentar yang menyasar kode dan menawarkan alternatif.

Referensi#

• Javadoc Tool — Oracle — penjelasan format komentar Javadoc dan pembuatan dokumentasi HTML.
• Specification for doc comments — Oracle Java SE 21 — spesifikasi resmi tag Javadoc untuk Java 21.
• Google Java Style Guide — Google — contoh panduan gaya Java yang sering menjadi dasar konfigurasi tim.