Komentar dan Gaya

Komentar tidak dijalankan oleh program, tetapi menentukan seberapa cepat kode dipahami kembali, baik oleh penulisnya sendiri maupun oleh pengembang lain. Kotlin menyediakan komentar satu baris, komentar blok, dan komentar dokumentasi KDoc, serta menetapkan konvensi pengodean resmi yang menjaga konsistensi seluruh kode. Topik ini membahas ketiga bentuk komentar beserta aturan gaya yang direkomendasikan dokumentasi resmi.

Komentar baris dan blok#

Komentar satu baris dimulai dengan // dan berlaku sampai akhir baris, sedangkan komentar blok berada di antara /* dan */ serta dapat melintasi beberapa baris. Buat berkas catatan.kt berikut yang memakai keduanya.

fun main() {
    // program penghitung karakter sederhana
    val kalimat = "Kotlin ringkas dan jelas" // komentar di akhir baris
    /* cetak jumlah karakter
       memakai properti length */
    println(kalimat.length)
}

# kompilasi catatan.kt dengan pustaka standar tersemat
kotlinc catatan.kt -include-runtime -d catatan.jar
# jalankan program
java -jar catatan.jar

24

Program tetap menghitung 24, yaitu banyaknya karakter pada kalimat tersebut, karena seluruh komentar diabaikan compiler dan tidak meninggalkan jejak pada bytecode. Komentar di akhir baris cocok untuk penjelasan singkat atas baris itu sendiri, sedangkan komentar blok cocok untuk uraian yang lebih panjang.

Komentar blok pada Kotlin dapat bersarang, yaitu /* di dalam /* yang ditutup berpasangan. Fitur ini jarang dimiliki bahasa lain, sehingga komentar yang berisi potongan kode dengan komentar di dalamnya tetap sah. Buat berkas nested.kt berikut untuk membuktikannya.

fun main() {
    /* komentar luar /* komentar bersarang */ masih komentar */
    println("Komentar bersarang didukung")
}

# kompilasi nested.kt dengan pustaka standar tersemat
kotlinc nested.kt -include-runtime -d nested.jar
# jalankan program
java -jar nested.jar

Komentar bersarang didukung

Penutup */ pertama menutup komentar dalam, dan komentar luar baru selesai pada penutup kedua. Pada bahasa yang tidak mendukung komentar bersarang, pola semacam ini justru memotong komentar luar terlalu cepat dan menyebabkan error kompilasi, sehingga perbedaan perilaku ini perlu diingat ketika berpindah bahasa.

Komentar dokumentasi KDoc#

KDoc adalah format komentar dokumentasi untuk Kotlin, ditulis dengan /** dan ditempatkan tepat di atas deklarasi fungsi, kelas, atau properti. Isinya mendeskripsikan perilaku deklarasi tersebut dan memakai tag seperti @param untuk setiap parameter serta @return untuk nilai kembaliannya. Buat berkas luas.kt berikut.

/**
 * Menghitung luas persegi panjang.
 *
 * @param panjang panjang sisi dalam sentimeter
 * @param lebar   lebar sisi dalam sentimeter
 * @return luas dalam sentimeter persegi
 */
fun luasPersegiPanjang(panjang: Int, lebar: Int): Int {
    return panjang * lebar
}

fun main() {
    val luas = luasPersegiPanjang(10, 24)
    println("Luas: $luas")
}

# kompilasi luas.kt dengan pustaka standar tersemat
kotlinc luas.kt -include-runtime -d luas.jar
# jalankan program
java -jar luas.jar

Luas: 240

Fungsi luasPersegiPanjang bekerja seperti fungsi biasa, tetapi kontraknya kini terdokumentasi di tempat deklarasinya. IDE menampilkan isi KDoc sebagai tooltip ketika fungsi itu dipanggil, dan alat pembangun dokumentasi seperti Dokka merangkum seluruh KDoc menjadi halaman dokumentasi. Penulisan @param untuk setiap parameter membuat penjelasan tetap menempel pada parameternya, sehingga tidak tertukar ketika urutan parameter berubah.

Isi KDoc ditulis sebagai teks biasa dengan penataan ala Markdown, sehingga daftar dan penekanan sederhana dapat dipakai tanpa format tambahan. Kalimat pertama sebaiknya merangkum fungsi dalam satu baris, karena kalimat itu yang paling sering tampil pada ringkasan dan tooltip. Sementara itu, komentar // biasa tetap dipakai untuk penjelasan di dalam tubuh fungsi, dan keduanya punya peran yang tidak saling menggantikan.

Konvensi pengodean resmi#

Konvensi pengodean (coding conventions) Kotlin menetapkan penamaan, indentasi, dan penataan yang membuat kode dari pengembang yang berbeda tetap terlihat seragam. Aturan penamaannya dibagi dua, yaitu camelCase dengan huruf awal kecil untuk fungsi, variabel, dan properti, serta PascalCase dengan huruf awal kapital untuk nama kelas dan objek. Konstanta yang tidak berubah ditulis dengan huruf kapital dan pemisah garis bawah.

Potongan berikut memperlihatkan penamaan tersebut pada satu deklarasi kelas beserta anggotanya.

// tidak-dijalankan
class JadwalPiket {          // PascalCase untuk nama kelas
    val jumlahHari = 7       // camelCase untuk properti

    fun cetakJadwal() {      // camelCase untuk fungsi
        println("Jadwal piket $jumlahHari hari")
    }
}

Aturan penataannya juga tetap sederhana, yaitu indentasi empat spasi, kurung kurawal pembuka di akhir baris yang sama dengan deklarasinya, dan satu spasi di sekitar operator. Nama paket ditulis seluruhnya dengan huruf kecil tanpa pemisah garis bawah, misalnya org.example.latihan. Konvensi ini bukan aturan compiler, sehingga kode yang melanggarnya tetap terkompilasi, tetapi kepatuhan padanya membuat code review berfokus pada isi alih-alih perbedaan gaya.

Kepatuhan pada konvensi tidak perlu menyulitkan, karena alat format otomatis yang menyertai IDE mengerjakan sebagian besar aturan penataan tanpa usaha manual. Penataan berjalan setiap berkas disimpan, sehingga selisih gaya antarpengembang terkoreksi sebelum sampai ke code review. Dengan pembagian itu, gaya bukan lagi keputusan pribadi yang berbeda di setiap berkas, melainkan pengaturan sekali yang ditegakkan konsisten oleh alatnya.

Ringkasan#

• Komentar satu baris memakai //, komentar blok memakai /* ... */, dan komentar blok Kotlin dapat bersarang.
• KDoc ditulis dengan /** ... */ di atas deklarasi, memakai tag @param dan @return, serta dibaca IDE dan alat dokumentasi seperti Dokka.
• Konvensi penamaan memakai camelCase untuk fungsi, variabel, dan properti, serta PascalCase untuk kelas dan objek.
• Indentasi empat spasi dan kurung kurawal pembuka di akhir baris merupakan bagian dari konvensi resmi yang ditegakkan secara konsisten oleh alat format.

Referensi#

• Coding conventions — Kotlin Documentation — Dokumentasi resmi konvensi penamaan, format, dan penataan kode Kotlin.
• Document Kotlin code: KDoc — Kotlin Documentation — Dokumentasi resmi format KDoc beserta tag dan bloknya.