Komentar di R: Cara Memberi Komentar pada Kode (dan Menonaktifkan Blok)

Simbol

Komentar di R dimulai dengan #. Dari karakter itu sampai akhir baris, R mengabaikan semuanya:

# This whole line is a comment. R skips it.
speed_kmh <- 90

speed_ms <- speed_kmh / 3.6  # convert to meters per second

print(speed_ms)

Kedua posisi itu sah: komentar di barisnya sendiri, atau komentar inline sesudah kode. Tidak ada yang perlu ditutup; komentar berakhir begitu barisnya berakhir. Satu # sudah cukup, dan # di dalam string yang diapit tanda kutip hanyalah karakter biasa, bukan komentar:

tag <- "#1 fan"  # the first # is data, this one is a comment
print(tag)

R Tidak Punya Komentar Multibaris

Inilah jawaban untuk pertanyaan yang cepat atau lambat dicari setiap pemula R: R tidak punya sintaks komentar blok. Tidak ada /* ... */, tidak ada """docstring""", tidak ada =begin/=end. Setiap baris yang dikomentari butuh # sendiri. Ini kesederhanaan yang disengaja dalam bahasanya, dan tidak semerepotkan kedengarannya, karena perangkat editor menutup kekurangan itu.

Solusi di dunia nyata: shortcut toggle di editormu. Di RStudio, pilih baris-barisnya lalu tekan Ctrl+Shift+C (Windows/Linux) atau Cmd+Shift+C (macOS). Setiap baris yang dipilih mendapat awalan #; tekan sekali lagi dan awalan itu hilang. Inilah yang benar-benar dilakukan programmer R, puluhan kali sehari, dan layak kamu jadikan kebiasaan minggu ini. VS Code, Vim, dan Emacs semuanya punya perintah toggle komentar yang setara untuk file R.

Trik if (FALSE). Karena FALSE tidak pernah benar, membungkus kode dengan if (FALSE) { ... } menjamin kode itu tidak pernah dijalankan:

if (FALSE) {
    expensive_call <- 1 / 0
    cat("you will never see this\n")
}

cat("but you will see this\n")

Ketahui trik ini, tetapi anggap sebagai keunikan saja, bukan kebiasaan, karena ada kelemahan nyata. Kode yang dilewati tetap harus berupa R yang sintaksnya valid: komentar blok sungguhan bisa menampung apa saja, tetapi if (FALSE) di sekitar baris yang setengah jadi adalah error parsing yang menghentikan seluruh script. Artinya juga bisa berubah diam-diam kalau kurung kurawalnya ikut teredit. Kalau kamu ingin baris-baris itu dinonaktifkan, shortcut editor lebih aman; kalau kamu ingin baris-baris itu hilang, hapus saja, itulah gunanya version control.

Isi Komentar yang Baik: Kenapa, Bukan Apa

Kodenya sudah menyatakan apa yang ia lakukan. Komentar yang mengulanginya hanyalah gangguan, yang suatu saat akan ketinggalan zaman dan mulai berbohong:

# Bad: narrates the obvious
x <- x + 1  # add 1 to x

# Good: explains the reason
x <- x + 1  # customer-facing IDs are 1-based, data is 0-based

Komentar kedua membawa informasi yang tidak bisa disampaikan kodenya: kenapa penambahan itu ada. Itulah ujian untuk setiap komentar yang kamu tulis: apakah ia menjelaskan maksud, konteks, atau keputusan yang tidak terlihat jelas? Komentar paling berguna di baris-baris yang aneh: solusi sementara untuk bug di sebuah package, selisih satu yang memang disengaja, rumus yang diambil dari makalah tertentu. Dan ingat aturan perawatannya: ketika kamu mengubah kode, ubah juga komentarnya, karena komentar yang salah lebih buruk daripada tidak ada komentar.

Kalau kamu sampai menulis komentar untuk menjelaskan isi sebuah variabel, sering kali solusi yang lebih baik adalah nama yang lebih jelas. Lihat variabel untuk pembahasan itu.

Judul Bagian yang Bisa Dilipat di RStudio

Script analisis bisa jadi panjang, dan komentar sekaligus berfungsi sebagai daftar isinya. RStudio memperlakukan baris komentar yang diakhiri empat atau lebih - (atau = atau #) sebagai judul bagian:

# Load data ----------------------------------------------------------

# Clean and reshape ----

# Model ====

Setiap bagian bisa dilipat dan muncul di outline dokumen RStudio, sehingga script 300 baris berubah menjadi daftar langkah yang mudah dijelajahi: muat, bersihkan, modelkan, buat plot. Karakter penutup mana pun boleh, asalkan minimal empat; pilih satu gaya dan pakai secara konsisten. Bahkan di luar RStudio, komentar judul bagian membuat struktur script terlihat sekilas, dokumentasi termurah yang bisa dimiliki sebuah analisis.

Komentar roxygen2: #' di Dunia Nyata

Saat membaca kode R milik orang lain, terutama source code package, kamu akan bertemu komentar yang diawali #':

#' Convert a speed from km/h to m/s
#'
#' @param kmh Speed in kilometers per hour.
#' @return Speed in meters per second.
kmh_to_ms <- function(kmh) {
    kmh / 3.6
}

Ini adalah komentar dokumentasi roxygen2. Ditulis tepat di atas definisi fungsi, komentar ini dikompilasi oleh perangkat package menjadi halaman bantuan resmi yang kamu baca dengan ?function_name. Tag-nya (@param, @return) menjelaskan input dan output fungsi. Bagi R sendiri, baris #' hanyalah komentar biasa; konvensi ini baru bermakna di dalam rangkaian alat pengembangan package. Kamu belum perlu menulisnya sampai kamu membuat package atau mendokumentasikan fungsi buatanmu dengan serius; untuk sekarang, cukup kenali bentuknya supaya source code package tidak terlihat misterius.

Yang Perlu Kamu Ingat

• # memulai komentar; komentar berlaku sampai akhir baris, baik barisnya berisi komentar saja maupun kode lalu komentar.
• R tidak punya komentar multibaris: aktifkan dan matikan komentar blok dengan Ctrl/Cmd+Shift+C di RStudio, dan simpan if (FALSE) {} untuk kode yang sintaksnya valid dan jarang kamu lewati.
• Komentari kenapa, bukan apa, dan perbarui komentar saat kodenya berubah.
• Komentar # Section name ---- memberi RStudio bagian yang bisa dilipat dan memberi pembaca peta script.
• Baris #' adalah komentar dokumentasi roxygen2 yang menjadi halaman bantuan package.

Berikutnya: variabel, yaitu cara membuatnya dengan <-, memberinya nama yang baik, dan cara R memperlakukan nilai yang disimpannya.