Tolong pertahankan penjelasan kode tetap sederhana

• Dalam code review, jika penjelasan panjang datang bersama diff besar, reviewer akan sulit menangkap alasan perubahan yang menjadi inti, sehingga pesan commit, deskripsi merge request, dan komentar harus ringkas
• Penjelasan sebaiknya berfokus pada mengapa berubah, bukan sekadar apa yang berubah, karena banyak perubahan bisa dilihat langsung dari kodenya
• Penjelasan panjang yang mencoba memuat semua konteks sekaligus dapat menurunkan fokus sebagian reviewer dan memperlambat kecepatan review
• Dalam merge review, commit yang atomik sangat penting; perbaikan kecil bisa ditangani dengan git amend, dan perapian sebelum penggabungan bisa dilakukan dengan rebase atau squash
• Meski memakai alat LLM, komentar, penjelasan, dan pesan commit sebaiknya ditulis sendiri karena lebih membantu pemahaman kode dan aksesibilitas review

---

Penjelasan review: fokus pada “mengapa”, bukan “apa”

• Dalam code review, ketika penjelasan, commit, dan merge request dipenuhi terlalu banyak informasi, beban peninjauan menjadi lebih besar
• Daripada menuliskan daftar panjang perubahan, yang utama adalah menjelaskan dengan jelas mengapa perubahan dilakukan
• Kode itu sendiri dapat menunjukkan sebagian besar perubahan, dan konteks yang kurang bisa ditanyakan oleh reviewer
• Penjelasan yang ditulis seperti teks panjang dapat memperlambat review bagi orang yang sulit mempertahankan fokus
• Pesan commit, deskripsi merge request, dan komentar kode sebaiknya jelas, langsung ke inti, dan hanya memuat informasi yang diperlukan

Permintaan tentang perapian commit dan penggunaan LLM

• Commit harus bersifat atomik, terutama dalam merge review, sehingga setiap perubahan dapat dipahami secara mandiri
• Perbaikan kecil bisa dimasukkan dengan git amend, dan sebelum penggabungan dapat dirapikan lewat rebase atau squash
• Meski menggunakan alat LLM, komentar, penjelasan, dan pesan commit dianggap lebih baik jika ditulis sendiri
  • Proses menulis sendiri membantu memahami isi perubahan
  • Penjelasan yang ditulis sendiri bisa lebih mudah diakses oleh reviewer
• Ada juga pendapat pribadi bahwa alat LLM sebaiknya dihindari jika memungkinkan
• Ada tanggapan terhadap penggunaan istilah aksesibilitas, tetapi inti pesannya adalah ajakan untuk membuat penjelasan code review lebih ringkas dan lebih mudah ditinjau

[GN⁺]

Pendapat di Lobste.rs

• Perlu hati-hati jika kebutuhan aksesibilitas disamakan begitu saja dengan selera pribadi tertentu
  Hanya karena seseorang punya ADHD bukan berarti tidak suka pesan commit yang panjang adalah ciri ADHD yang universal, dan aksesibilitas lebih dekat ke penyesuaian yang wajar agar tidak membebani pengguna umum secara berlebihan, bukan “melakukan semua sesuai yang disukai orang dengan ADHD”
  Karena itu, banyak fitur aksesibilitas ditempatkan di balik pengaturan yang bisa dipilih sendiri, seperti kontras tinggi, pengurangan gerakan, dan mode gelap

  • Mungkin saya bisa menulisnya dengan lebih jelas, tetapi AuDHD saya memang memerlukan kondisi tertentu agar bisa bekerja dan berfungsi dengan baik
    Blok teks panjang, misalnya ketika perubahan kecil disertai penjelasan sepanjang dua halaman A4, bisa benar-benar menghambat pekerjaan, dan kalau dipaksa dibaca bisa berujung burnout
    Sepertinya lebih tepat jika diungkapkan sebagai “ini adalah kebutuhan aksesibilitas saya, dan saya tahu ada banyak orang yang mirip”
    Tetap saja, ini mungkin bisa dianggap sebagai preferensi, tetapi ini permintaan agar saat menempelkan dinding teks buatan LLM ke pesan commit, orang seperti saya juga dipertimbangkan
  • Beda tiap orang, tetapi menurut saya “tolong sampaikan inti dulu” cukup merupakan salah satu ciri inti ADHD
    Dari sisi aksesibilitas juga, semua orang mendapat manfaat dari penyesuaian ini, jadi rasanya tidak ada alasan kuat untuk menolaknya
  • Dari pengalaman saya, cukup banyak kesulitan yang tidak perlu yang dialami orang neurodivergen dan penyandang disabilitas muncul karena kebutuhan aksesibilitas dianggap sekadar selera
    Jika aksesibilitas meningkat, bahkan orang yang tidak mutlak memerlukan fitur itu untuk berdiri di garis start yang setara juga ikut diuntungkan, jadi bergerak ke arah itu adalah hal yang baik

• Sejak sebelum era AI saya memang selalu menyukai komentar yang terlalu rinci, dan banyak orang yang pernah bekerja dengan saya juga terkejut karenanya
  Misalnya ada metode ini: https://github.com/ghostty-org/ghostty/…
  Selama 15 tahun terakhir, terlepas dari bahasanya, saya pada dasarnya menulis dengan gaya seperti ini, dan di era AI saya juga mencantumkan pendekatan ini di AGENTS.md
  File dan komentar yang saya tautkan semuanya ditulis manusia dan sama sekali tidak memakai AI
  Alasannya sederhana: ini memaksa aturan pencatatan ganda agar komentar dan kode harus saling cocok
  Jika keduanya tidak cocok, berarti komentarnya salah, atau kodenya salah, atau keduanya salah, dan hanya dengan bertanya “yang benar yang mana?” banyak masalah bisa ditemukan
  Pada akhirnya, kalau itu proyek Anda sendiri, saya rasa masing-masing bebas memberi komentar dengan cara yang diinginkan

  • Saya juga kadang menerima candaan akrab bahwa saya menulis lebih banyak komentar daripada kode, dan saya benar-benar menyukai komentar seperti ini
    Saat membaca ulang kode nanti, komentar seperti ini menjaga konteks keputusan lokal yang saya ambil saat itu, dan juga membantu reviewer atau orang yang baru pertama melihatnya membangun konteks
    Komentar seperti ini memang panjang, tetapi bukan “detail yang tidak perlu” seperti yang dibahas dalam tulisan itu, dan contoh yang dibagikan tampak seperti contoh yang baik dari pepatah “jelaskan mengapa, bukan apa”
  • Komentar seperti ini luar biasa
    Seperti pada contoh, komentar yang menjelaskan mengapa pengguna macOS menaruh konfigurasi shell di ~/.bash_profile dan lalu mengharapkan login shell memberi konteks yang berguna tentang alasan sebuah keputusan diambil
    Namun kalau kembali ke LLM, secara pribadi saya belum pernah melihat komentar buatan LLM dengan kualitas seperti itu
    Biasanya hanya mengulang hal-hal yang sudah jelas dari membaca kodenya saja, seperti melakukan foo(), lalu bar(), dan terakhir baz
  • Jenis komentar yang ditautkan itu tidak masalah
    Masalahnya adalah kekacauan berupa tabel besar dan daftar bullet raksasa yang ditempelkan bahkan untuk perubahan yang sangat kecil
  • Tingkat detail seperti itu memang sangat saya hargai, tetapi secara pribadi saya lebih suka jika itu masuk ke pesan commit dari commit yang menambahkan metode tersebut daripada ke komentar
    Pesan commit akan tetap menjadi catatan pada saat yang sama dengan kodenya, sedangkan komentar terasa bisa melenceng seiring waktu
  • Komentar yang dimulai di baris 1467 itu benar-benar mahakarya, dan rasa lelahnya terasa sekali

• Di tempat kerja saya pernah dengan sopan menuliskan di template PR, “tolong jelaskan langsung motivasi perubahan ini dan keputusan desain penting yang perlu diperhatikan saat review”
  Tetapi 9 dari 10 kali, LLM yang sedang dipakai saat itu malah membuang seluruh template tersebut, lalu memuntahkan penjelasan panjang yang berisi jumlah tes yang ditambahkan, checkbox lulus, dan cabang pembahasan panjang untuk hal-hal sepele
  Alhasil review jadi sangat menyenangkan

  • Di tempat kerja saya juga ada masalah yang sama
    Saya tidak tahu siapa yang menganggap menyisipkan alat pesan commit buatan LLM di mana-mana itu ide bagus, tetapi akhirnya di dalam commit muncul masalah https://noslopgrenade.com/
    Di pesan commit atau deskripsi pull request tidak ada konteks berguna seperti motivasi perubahan, keputusan desain, atau alasannya, dan isinya berubah menjadi paragraf yang menguraikan detail implementasi yang sebenarnya sudah bisa diketahui hanya dengan membaca kodenya
  • Saya juga melihat perilaku yang sama
    Saya sedang mempertimbangkan menambahkan ke agents.md kalimat “saat menulis pesan commit, rujuk commit-messages.md”
    Di commit-messages.md sepertinya bisa dimasukkan panduan pesan commit seperti larangan checkbox tes lulus/gagal, serta meringkas daftar tes individual atau tidak menuliskannya sama sekali

• Saya menulis komentar tentang apa yang saya lakukan hanya ketika masalahnya bukan mengapa saya melakukannya, melainkan ketika saya sendiri tidak yakin apakah cara itu benar
  Penyebab utama yang berulang kali menyiksa adalah regular expression

  • Saya juga sama
    Kadang memang ada saatnya semua hal harus dijelaskan dengan kokoh, tetapi belakangan ini saya melihat bahkan perubahan kecil seperti mengganti nama variabel pun diberi penjelasan raksasa

• Menariknya, saya justru sering diberi tahu bahwa pesan commit saya terlalu pendek

  • Diskusi dalam tulisan ini berdampingan dengan tulisan Chesterton middle finger yang mengeluh ke arah sebaliknya, yaitu penjelasannya terlalu pendek
  • Bisa saja terlalu pendek, tetapi memasukkan satu novel penuh ke sana juga tidak masuk akal
  • LLM benar-benar menulis terlalu banyak
    Karena itu saya mengatur agar claude sama sekali tidak menulis komentar, karena saya akhirnya menghapus 98% secara manual dan bahkan 2% yang tersisa pun saya tulis ulang sendiri

• Saya biasanya menyukai pesan commit yang sangat deskriptif, tetapi cenderung menyusunnya seperti struktur artikel berita: informasi paling penting diletakkan lebih dulu, lalu detail yang kurang penting namun tetap relevan di belakang
  Misalnya, judul memuat informasi terpenting sepadat mungkin, paragraf pertama menjelaskan perubahan dengan kalimat yang tidak terlalu dipadatkan, lalu paragraf-paragraf berikutnya berisi detail tambahan yang tidak perlu dibaca saksama kecuali memang sulit memahami sifat perubahan kode tersebut
  Menurut saya, pentingnya pesan commit bagi orang yang kelak membaca kode sering diremehkan
  Saat menggali codebase dan penasaran mengapa suatu blok ditulis seperti itu, saya tidak pernah kecewa ketika git blame membawa saya ke pesan commit yang menjelaskan dengan sangat rinci bahwa pendekatan yang sekarang tampak canggung itu sebenarnya adalah pilihan yang tersisa setelah beberapa pendekatan lain yang tampak lebih baik ternyata tidak lengkap
  Kembali ke pokok tulisan penulis, menambahkan penanda yang eksplisit dalam komunikasi adalah penyesuaian yang baik dan secara umum juga berguna
  Anda bisa menaruh kalimat seperti “jika Anda sedang me-review kode ini, Anda boleh berhenti membaca di sini” di tengah pesan commit

• Ungkapan “detail yang tidak perlu bisa ditanyakan bila diperlukan” adalah asumsi berani bahwa orang tersebut akan terus ada di sekitar
  Saya mulai rajin menulis pesan commit setelah mulai berkontribusi ke codebase FLOSS yang usianya sudah lebih dari 10 tahun
  Satu-satunya cara untuk mengetahui lebih jauh mengapa kode itu ada dalam bentuk tersebut adalah arkeologi git, dan saya belajar vc-annonate di Emacs agar lebih mudah menelusurinya
  Bahkan di kode kantor, beberapa kali saya memelihara codebase yang penulis aslinya sudah lama pergi
  Pesan commit tidak hanya dibaca saat review, bahkan banyak UI review justru menyembunyikan pesan commit
  Masalahnya tampaknya bukan pada pesan commit yang panjang, melainkan pesan commit yang ditulis dengan buruk
  Pedoman seperti “pesan commit, deskripsi merge request, dan komentar kode harus ditulis dengan jelas dan langsung ke inti sesuai kebutuhan, serta menjelaskan mengapa, bukan apa” terdengar bagus
  Bisa jadi masalahnya adalah orang yang sebelumnya hanya menulis Fix Bugz 🚀️ sekarang menulis pesan commit dengan LLM sambil mengaku mengikuti “praktik terbaik”
  Hipotesis saya, kebanyakan orang tidak menulis pesan commit karena mereka tidak membacanya, dan mereka tidak membacanya karena energi aktivasi untuk mencarinya tinggi ketika menelusuri commit dengan bergantung pada hal-hal seperti antarmuka web GitHub

  • “detail yang tidak perlu bisa ditanyakan bila diperlukan” itu berlaku dalam konteks review
    Jika informasi itu penting, Anda bisa meninggalkannya sebagai komentar atau menambahkannya ke pesan commit
    KDE sudah memakai Gitlab selama beberapa tahun

• Dalam jangka panjang, diperlukan keseimbangan demi arkeologi git yang berhasil bagi generasi berikutnya
  Karena pergantian orang atau konteks yang hilang dari kepala, sering kali nanti tidak ada lagi kesempatan untuk menanyakan detail yang sekarang tampak tidak perlu itu
  Waktu terbaik untuk mencatat konteks tersebut adalah saat kita masih memilikinya
  Yang benar-benar diinginkan mungkin adalah menaruh detail penting lebih dulu, dengan pemisahan yang jelas seperti ringkasan

• PR atau penjelasan kode bukan untuk apa yang dilakukan, melainkan untuk mengapa hal itu dilakukan
  Penjelasan itu harus memberi tahu mengapa kode ini berbentuk seperti sekarang dan alasan di baliknya
  Ini baik untuk review, dan juga baik nanti saat mencari di riwayat git mengapa kode tersebut menjadi seperti itu

• Menjaga penjelasan kode tetap sederhana itu penting
  Karena sesuatu yang tidak bisa dipahami atau tidak bisa menjadi fokus, tidak bisa dibaca
  Pada saat yang sama, saat mengembangkan perangkat lunak, banyak konteks yang menghilang, dan sekarang konteks itu hanya ada di kepala penulis, orang yang pernah berbicara dengan penulis, atau orang yang sudah menelaah kode secara mendalam
  Namun saya rasa konteks itu harus lebih terjalin dengan kode, bukan malah kurang
  Karena kita tidak selalu bisa berbicara dengan penulisnya, hal itu harus ditulis di tempat yang selalu bisa diakses dan diperbarui bersama kode
  Dalam kebanyakan alur pengembangan saat ini, tempat yang paling cocok untuk itu adalah pesan commit git
  Menulis ringkasan di bagian atas itu bagus, tetapi saya juga menyarankan agar penjelasan tambahan tentang perubahan kode tetap ditinggalkan
  Jika konteks dikeluarkan dan dicatat, termasuk hal-hal yang sekarang tampak tidak penting, diri saya di masa depan akan berterima kasih
  Ke depan, diperlukan pendekatan yang lebih baik daripada hanya menaruh konteks semacam itu di pesan commit, dan karena itu secara pribadi saya menyukai pemrograman literer, yang memberi lebih banyak ruang untuk menjelaskan “apa” dan “mengapa” dari kode