Inilah pertanyaan yang ingin saya tanyakan pada diri sendiri ketika memikirkan apakah akan menambahkan komentar ke dalam bagian kode: Apa yang dapat saya sampaikan yang akan membantu orang berikutnya memahami maksud keseluruhan kode dengan lebih baik, sehingga mereka dapat memperbarui, memperbaiki, atau memperpanjangnya lebih cepat dan lebih andal?
Kadang-kadang jawaban yang benar untuk pertanyaan ini adalah bahwa tidak ada banyak yang dapat Anda tambahkan pada saat itu dalam kode, karena Anda sudah memilih nama dan konvensi yang membuat maksudnya sejelas mungkin. Itu berarti Anda telah menulis kode self-documenting yang solid, dan memasukkan komentar di sana kemungkinan akan mengurangi lebih banyak daripada yang dapat membantu. (Perhatikan bahwa komentar yang berlebihan dapat benar-benar merusak keandalan kode dari waktu ke waktu dengan memperlambat ketidakselarasan dengan kode nyata dari waktu ke waktu dan dengan demikian mempersulit penguraian maksud sebenarnya.
Namun, di hampir semua program dan dalam bahasa pemrograman apa pun, Anda akan menemui titik di mana konsep dan keputusan penting tertentu yang dibuat oleh programmer asli - oleh Anda - tidak lagi terlihat dalam kode. Ini cukup banyak tidak dapat dihindari karena seorang programmer yang baik selalu memprogram untuk masa depan - yaitu, tidak hanya membuat program bekerja satu kali, tetapi untuk membuat semua perbaikan di masa depan dan versi dan ekstensi dan modifikasi dan port dan siapa yang tahu apa yang harus juga berfungsi dengan benar. Seperangkat tujuan yang terakhir jauh lebih sulit, dan membutuhkan lebih banyak pemikiran untuk melakukannya dengan baik. Juga sangat sulit untuk mengekspresikan dengan baik di sebagian besar bahasa komputer, yang lebih fokus pada fungsionalitas - yaitu, mengatakan apa yang melakukan ini versi program perlu dilakukan, saat ini, untuk membuatnya memuaskan.
Inilah contoh sederhana tentang apa yang saya maksud. Dalam kebanyakan bahasa, pencarian in-line cepat dari struktur data kecil akan memiliki kompleksitas yang cukup sehingga seseorang yang melihatnya untuk pertama kali kemungkinan tidak akan langsung mengenali apa itu. Itu adalah peluang untuk komentar yang baik, karena Anda dapat menambahkan sesuatu tentang maksud kode Anda yang mungkin akan segera dihargai oleh pembaca sebagai bantuan untuk menguraikan detail.
Sebaliknya, dalam bahasa seperti bahasa berdasarkan logika-Prolog, mengungkapkan pencarian dari daftar kecil bisa jadi sangat sepele dan ringkas bahwa setiap komentar Anda bisa menambahkan hanya akan menjadi kebisingan. Jadi, komentar yang baik tentu tergantung pada konteks. Itu termasuk faktor-faktor seperti kekuatan bahasa yang Anda gunakan dan keseluruhan konteks program.
Intinya adalah ini: Pikirkan masa depan. Tanyakan kepada diri sendiri apa yang penting dan jelas bagi Anda tentang bagaimana program harus dipahami dan dimodifikasi di masa depan. [1]
Untuk bagian-bagian dari kode Anda yang benar-benar mendokumentasikan diri, komentar cukup tambahkan noise dan tingkatkan masalah koherensi untuk versi yang akan datang. Jadi jangan menambahkannya di sana.
Tetapi untuk bagian-bagian kode Anda di mana Anda membuat keputusan kritis dari beberapa opsi, atau di mana kode itu sendiri cukup kompleks sehingga tujuannya tidak jelas, tolong, tambahkan pengetahuan khusus Anda dalam bentuk komentar. Sebuah komentar yang baik dalam kasus seperti itu adalah komentar yang membuat beberapa programmer di masa depan tahu apa yang harus dijaga tetap sama - yaitu konsep pernyataan invarian, secara kebetulan - dan apa yang boleh diubah.
[1] Ini melampaui masalah komentar, tetapi layak untuk dibahas: Jika Anda menemukan ide yang sangat tajam tentang bagaimana kode Anda dapat berubah di masa mendatang, Anda mungkin harus berpikir lebih dari sekadar membuat komentar dan menyematkan parameter-parameter itu. di dalam kode itu sendiri, karena itu akan selalu menjadi cara yang lebih dapat diandalkan untuk memastikan keandalan versi kode Anda di masa mendatang daripada mencoba menggunakan komentar untuk mengarahkan orang yang tidak dikenal di masa depan ke arah yang benar. Pada saat yang sama Anda juga ingin menghindari generalisasi yang berlebihan, karena manusia terkenal buruk dalam memprediksi masa depan, dan itu termasuk masa depan perubahan program. Jadi, cobalah untuk mendefinisikan dan menangkap dimensi masa depan yang masuk akal dan terbukti dengan baik di semua tingkat desain program, tetapi jangan