Why Not Comments

• Mengapa bukan komentar "why not"? Bukan mengapa "tidak memberi komentar"
  • “Mengapa Anda tidak meninggalkan komentar tentang ‘mengapa ini tidak berhasil’? Bukan menanyakan alasan ‘mengapa Anda tidak menambahkan komentar’.”

Why Not Comments

• Kode ditulis dalam bahasa mesin yang terstruktur, sedangkan komentar ditulis dalam bahasa manusia yang kaya ekspresi
• Artinya, jangan beri komentar tentang "apa", tetapi masukkan sebanyak mungkin informasi ke dalam identifier
• Belakangan ini, ada juga pendapat bahwa "mengapa" pun jangan dimasukkan ke komentar, melainkan ke dalam LongFunctionNames atau nama test case
• Codebase yang "self-documenting" menambahkan dokumentasi melalui identifier

Contoh terbaru

• Contoh dari Logic for Programmers
• Terjadi masalah saat build epub tidak bisa mengubah simbol matematika (\forall) menjadi karakter (∀)
• Dibuat skrip yang secara manual mengganti token string matematika menjadi Unicode
• Ditulis dengan cara mengganti masing-masing dari 16 simbol matematika, tetapi ini tidak efisien
• Diselesaikan dengan cara sederhana lewat komentar
  • "Untuk setiap string, ini diulang 16 kali, tetapi saat ini buku tersebut hanya memiliki 25 string matematika dan sebagian besar panjangnya kurang dari 5 karakter, jadi tetap cukup cepat"

Mengapa perlu menulis komentar

• Alasan tetap perlu menulis komentar meskipun kode lambat tidak menimbulkan masalah
• Di masa depan, kode itu bisa menjadi masalah
• Komentar menunjukkan bahwa kita sadar akan trade-off yang ada
• Saat meninjau proyek lagi nanti, kita bisa memahami mengapa menulis kode yang lambat

Mengapa self-documenting tidak mungkin sepenuhnya

• Nama fungsi panjang seperti "RunFewerTimesSlowerAndSimplerAlgorithmAfterConsideringTradeOffs" tidak menjelaskan trade-off tersebut
• Identifier fungsi dan variabel hanya bisa memuat satu jenis informasi
• Juga tidak mungkin mengganti komentar dengan test
• Self-documenting menjelaskan apa yang dilakukan kode, tetapi informasi negatif menjelaskan apa yang tidak dilakukan kode

Spekulasi di akhir newsletter

• Ada rasa penasaran apakah komentar "mengapa tidak" bisa dianggap sebagai kasus kontrafaktual
• Apakah abstraksi dalam komunikasi manusia memang tidak bisa dibuat self-documenting?
• Bisakah analogi, ketidakpastian, argumen etis, dan sebagainya dibuat self-documenting?

---

Ringkasan GN⁺

• Artikel ini membahas pentingnya komentar kode dan keterbatasannya
• Melalui komentar, trade-off dalam kode dapat diperjelas dan maintenance di masa depan menjadi lebih mudah
• Menekankan keterbatasan self-documenting dan perlunya komentar

[GN⁺]

Opini Hacker News

• Saat menulis komentar pada kode, yang terutama dijelaskan adalah "mengapa" dan "mengapa tidak bisa". Untuk kode yang kompleks, menjelaskan secara singkat "apa" yang dilakukan juga berguna

  • Komentar yang diwajibkan itu tidak efisien, dan memberi komentar pada setiap fungsi adalah pemborosan waktu
  • Komentar yang ditambahkan otomatis oleh alat juga tidak efisien

• Engineer junior menulis komentar yang menjelaskan apa yang dilakukan kode, engineer menengah menjelaskan mengapa ditulis seperti itu, dan engineer senior menjelaskan alasan tidak menulisnya dengan cara lain

• Menggunakan template komentar untuk para maintainer

  • "Kode ini ditulis seperti ini karena <alasan>. Jika Anda mencoba mengubahnya lalu menyadari itu kesalahan, tolong tingkatkan penghitung ini untuk orang berikutnya: total_hours_wasted_here = n"

• Penting untuk memberi komentar pada bagian kode yang terasa mengejutkan

  • Saat tidak yakin apakah kode ini nanti masih akan mudah dipahami, tulis komentar yang menjelaskan "mengapa tidak bisa"

• Menekankan pentingnya komentar, terutama berguna ketika harus memelihara kode sendiri bahkan 5, 10, atau 15 tahun kemudian

  • Penting untuk menjaga konsistensi dengan kode yang sudah ada

• Sebaiknya beri komentar pada hal-hal yang "bukan solusi naif"

  • Kode yang tidak efisien bisa menimbulkan masalah saat nanti diperbaiki

• Baik juga memasukkan komentar ke dalam nama fungsi yang panjang atau nama test case

  • Saat nama metode tidak cukup jelas, komentar akan membantu
  • Jika deskripsi metode mengandung kata "dan", itu tanda bahwa metode tersebut melakukan terlalu banyak hal

• Berguna juga menambahkan peringatan melalui debug logging ketika input lebih besar daripada batasan desain awal

• Lebih suka banyak menggunakan komentar dan komentar dokumentasi

  • Menulis komentar untuk tiap tahap aplikasi, lalu merinci komentar itu sambil menulis kode
  • Lebih suka memberi komentar pada semua fungsi dan variabel

• Dalam code review, menulis komentar seperti "alasan tidak melakukan X adalah karena Y" untuk mencegah kritik yang sudah bisa diperkirakan sebelumnya