Foundation

BAB 3: Komentar

Komentar di Rust: komentar baris dan blok yang boleh bersarang, komentar dokumentasi /// dan //!, serta hasil nyata rustdoc dari komentar itu.

Komentar tidak mengubah hasil program. Berkas dengan 1 baris komentar dan berkas tanpa komentar menghasilkan keluaran yang sama persis saat dijalankan, dan kompilator membuang keduanya sebelum kode mesin dibuat. Yang berubah karena komentar adalah berkas dokumentasi yang bisa dihasilkan dari kode.

Rust punya 2 kelompok komentar: komentar biasa yang diabaikan sepenuhnya, dan komentar dokumentasi yang dibaca rustdoc. Bab ini menunjukkan keduanya dengan bukti dari kompilator dan keluaran rustdoc.

Komentar baris

Komentar baris dimulai dengan // dan berlaku sampai akhir baris. Semua teks sesudahnya diabaikan.

RSRUST
fn main() {
    // menghitung luas persegi dengan sisi 4
    let sisi = 4;
    let luas = sisi * sisi;
    println!("luas = {luas}"); // dicetak ke stdout
}
CodeTEXT
luas = 16

Komentar setelah kode pada baris yang sama sering dipakai untuk menjelaskan 1 baris tertentu. Komentar di baris sendiri dipakai untuk menjelaskan blok di bawahnya.

Komentar blok

Komentar blok dimulai dengan /* dan diakhiri */. Komentar ini bisa memuat beberapa baris, dan di Rust komentar blok boleh bersarang:

RSRUST
/* komentar luar /* komentar dalam */ masih di luar */
fn main() {
    println!("komentar tidak mengubah keluaran");
}
CodeTEXT
komentar tidak mengubah keluaran

Kemampuan bersarang ini berbeda dari C dan JavaScript, yang mengakhiri komentar pada */ pertama. Karena itu menonaktifkan sebagian kode yang sudah berisi komentar blok tetap aman dilakukan di Rust, tanpa memotong komentar secara tak sengaja.

Untuk menonaktifkan sementara beberapa baris kode, cara yang lebih umum adalah // di awal setiap baris. Editor modern menambahkan dan melepasnya sekaligus dengan pintasan, sehingga tidak perlu diketik satu per satu.

Komentar tidak menghilangkan peringatan

Komentar tidak memengaruhi pemeriksaan kompilator. Variabel yang tidak dipakai tetap dilaporkan sebagai peringatan, walaupun ada komentar yang menjelaskan maksudnya:

RSRUST
fn main() {
    // komentar tidak menghilangkan peringatan
    let tidak_dipakai = 5;
    println!("selesai");
}
CodeTEXT
warning: unused variable: `tidak_dipakai`
 --> komentar_warning.rs:3:9
  |
3 |     let tidak_dipakai = 5;
  |         ^^^^^^^^^^^^^ help: if this is intentional, prefix it with an underscore: `_tidak_dipakai`
  |
  = note: `#[warn(unused_variables)]` (part of `#[warn(unused)]`) on by default

Kalau maksudnya memang membiarkan variabel tidak dipakai, solusinya menambah garis bawah di depan nama, bukan menulis komentar. Kompilator membaca nama, bukan penjelasan.

Komentar dokumentasi

2 bentuk komentar dokumentasi dibaca rustdoc dan dipakai untuk menghasilkan halaman dokumentasi:

BentukBerlaku untuk
///item di bawahnya, misalnya fungsi atau struct
//!berkas atau modul tempat komentar itu ditulis
RSRUST
//! Dokumentasi tingkat crate.
//! Baris kedua.

/// Menambahkan 2 angka.
pub fn tambah(a: i32, b: i32) -> i32 {
    a + b
}

fn main() {
    println!("{}", tambah(2, 3));
}

Komentar jenis ini tidak mengubah hasil program, tetapi bisa diolah menjadi dokumentasi HTML:

CodeTEXT
rustdoc dokumen.rs -o doc

Perintah itu menghasilkan doc/dokumen/index.html sebesar 3.119 byte dan doc/dokumen/fn.tambah.html sebesar 3.447 byte. Halaman fungsi itu memuat uraian dari komentar /// di atasnya, dan halaman utamanya memuat uraian dari komentar //!.

Pada proyek cargo, perintah yang dipakai adalah cargo doc, yang mengumpulkan dokumentasi seluruh modul sekaligus. Hasilnya bisa dibuka langsung dengan cargo doc --open. Komentar /// juga bisa dipasang pada field struct dan varian enum, dan rustdoc menampilkannya di halaman tipe yang bersangkutan.

Isi komentar dokumentasi memakai Markdown, sehingga daftar, tautan, dan blok kode bisa ditulis di dalamnya. Blok kode pada komentar dokumentasi bisa dijalankan sebagai uji. Pada crate pustaka, cargo test --doc menjalankan blok itu, dan hasil uji saya untuk 1 fungsi sederhana: 1 passed; 0 failed, selesai dalam 0,28 detik. Fitur ini hanya bekerja pada crate pustaka (src/lib.rs), bukan pada crate biner yang memakai src/main.rs.

Apa yang layak ditulis sebagai komentar

Komentar yang berguna menjawab pertanyaan yang tidak bisa dijawab kode. 3 jenis yang saya pakai:

  1. Alasan di balik keputusan, misalnya mengapa 1 batas ditulis 250 dan bukan 255.
  2. Batasan yang tidak terlihat, misalnya fungsi yang hanya aman dipanggil setelah data tertentu dimuat.
  3. Rujukan ke aturan luar, misalnya nomor pasal atau tautan dokumentasi API.

Komentar yang mengulang kode tidak menambah informasi:

RSRUST
fn main() {
    let sisi = 4;

    // buruk: mengulang apa yang sudah terlihat
    let luas = sisi * sisi; // mengalikan sisi dengan sisi

    // berguna: menjelaskan alasan
    // sisi dibatasi 4 karena kanvas hanya menerima 4 satuan
    let luas = sisi * sisi;

    println!("{luas} dan {luas}");
}

Komentar juga cepat basi. Kode yang diubah tanpa memperbarui komentarnya meninggalkan penjelasan yang salah, dan pembaca berikutnya akan mempercayai komentar itu. Karena itu komentar yang menjelaskan mekanisme sebaiknya diganti dengan nama fungsi atau variabel yang lebih jelas.

Teks di dalam string bukan komentar

Tanda // hanya berfungsi sebagai komentar di luar string. Di dalam string, tanda itu dicetak apa adanya:

RSRUST
fn main() {
    println!("http://contoh.test // bukan komentar");
}
CodeTEXT
http://contoh.test // bukan komentar

Hal yang sama berlaku untuk /* */. Karena itu alamat situs dan potongan kode yang memuat tanda tersebut tidak perlu di-escape saat ditulis di dalam string.

Mematikan peringatan dengan atribut, bukan komentar

Kalau peringatan memang ingin dimatikan, Rust menyediakan atribut untuk itu. Atribut ditulis dengan tanda #[...] di atas item yang dituju, dan berbeda dari komentar karena dibaca kompilator:

RSRUST
fn main() {
    #[allow(unused_variables)]
    let tidak_dipakai = 5;
    println!("selesai tanpa peringatan");
}
CodeTEXT
selesai tanpa peringatan

Kompilasi berjalan tanpa peringatan unused_variables, karena atribut itu memerintahkan kompilator melewati pemeriksaan untuk item di bawahnya. Perhatikan bedanya: komentar menjelaskan kepada manusia, atribut memerintah kompilator. Menuliskan #[allow] di dalam komentar tidak berpengaruh apa pun.

Memakai atribut ini sebaiknya jarang. Mematikan peringatan pada seluruh berkas dengan #![allow(...)] menyembunyikan masalah yang mungkin muncul kemudian, termasuk variabel yang sebenarnya lupa dipakai.

Komentar sebagai penanda pekerjaan

Komentar juga dipakai sebagai penanda yang bisa dicari, misalnya TODO untuk pekerjaan yang belum selesai dan FIXME untuk bagian yang diketahui salah. Karena keduanya hanya teks, pencarian memakai alat biasa sudah cukup:

CodeTEXT
grep -rn "TODO" src/

Manfaat penanda seperti ini bergantung pada kebiasaan membersihkannya. Daftar TODO yang tidak pernah ditinjau berubah menjadi catatan yang menyesatkan, sama seperti komentar yang tidak diperbarui setelah kodenya berubah.

Komentar tidak masuk ke biner

Komentar dibuang sebelum kode mesin dibuat, sehingga berkas hasil kompilasi tidak berubah karena komentar. Saya mengompilasi 1 berkas yang sama 2 kali, pertama tanpa komentar dan kedua dengan 4 komentar, lalu membandingkan hasilnya:

CodeTEXT
md5sum bin1 bin2
48b92b2006624d9d52d3752885affa6e  bin1
48b92b2006624d9d52d3752885affa6e  bin2

Kedua biner identik sampai ke byte, dan cmp menyatakan tidak ada perbedaan. Yang berubah hanya isi berkas sumber: baris kode tetap di nomor yang sama atau bergeser, tergantung letak komentar, dan itulah yang terlihat di pesan kesalahan kompilator.

Menempatkan komentar

Komentar di baris sendiri cocok untuk menjelaskan blok kode di bawahnya. Komentar di akhir baris kode cocok untuk menjelaskan 1 baris, tetapi sebaiknya pendek; kalau lebih dari beberapa kata, pindahkan ke baris sendiri di atas kode.

RSRUST
fn main() {
    let total = 3 * 4;

    // total dipakai 2 kali di bawah, jadi disimpan di variabel
    println!("total = {total}");
    println!("keliling = {}", total + 2); // sisi luar
}

Konsistensi penempatan membuat kode lebih mudah dipindai. Pembaca terbiasa melihat penjelasan blok di atas blok, dan penjelasan 1 baris di ujung baris yang sama.

Ringkasan

Komentar baris memakai //, komentar blok memakai /* */, dan komentar blok di Rust boleh bersarang. Keduanya dibuang saat kompilasi sehingga tidak mengubah hasil program, dan tidak menghilangkan peringatan kompilator.

Komentar dokumentasi memakai /// untuk item dan //! untuk berkas atau modul, lalu diolah rustdoc menjadi halaman HTML. Pada proyek cargo, cargo doc mengumpulkan seluruh dokumentasi, dan komentar yang berguna menjelaskan alasan atau batasan, bukan mengulang isi kode.

Referensi

  1. The Rust Programming Language. Comments.
  2. The Rust Reference. Comments.