Pemeliharaan kode: Untuk menambahkan komentar dalam kode atau membiarkannya di kontrol versi?

Kami telah diminta untuk menambahkan komentar dengan tag awal, tag akhir, deskripsi, solusi dll untuk setiap perubahan yang kami lakukan pada kode sebagai bagian dari perbaikan bug / penerapan CR.

Kekhawatiran saya adalah, apakah ini memberikan nilai tambah? Karena itu, kami memiliki semua detail dalam riwayat kontrol Versi, yang akan membantu kami melacak setiap perubahan?

Tetapi para pemimpin saya bersikeras meminta komentar-komentar itu sebagai praktik pemrograman yang "baik". Salah satu argumen mereka adalah ketika CR harus dide-scoped / diubah, itu akan menjadi rumit jika komentar tidak ada.

Mempertimbangkan bahwa perubahan akan sebagian besar di antara kode, apakah akan sangat membantu untuk menambahkan komentar untuk setiap perubahan yang kita buat? Tidakkah seharusnya kita menyerahkannya ke kontrol versi?

Anda benar sekali. Pelacakan perubahan adalah pekerjaan untuk sistem kontrol versi Anda. Setiap kali Anda melakukan komit, Anda harus menulis pesan komit yang menjelaskan apa yang telah dilakukan, dan merujuk sistem pelacakan bug Anda jika ini adalah perbaikan bug. Menempatkan komentar di dalam pepatah kode

// begin fix for bug XXXXX on 10/9/2012
...
// end fix for bug XXXXX

setiap kali Anda memperbaiki bug akan dengan cepat membuat kode Anda tidak dapat dibaca dan tidak dapat dipelihara. Ini juga akan mengakibatkan duplikasi informasi yang sama di dua tempat, yang akan membuat kekacauan semakin parah.

Komentar tidak boleh digunakan untuk pelacakan bug dan mereka juga tidak boleh menggambarkan apa yang dilakukan kode Anda. Mereka harus menjelaskan mengapa Anda melakukan X, atau mengapa Anda melakukan X dengan cara khusus ini. Jika Anda merasa perlu untuk menulis komentar yang menjelaskan apa yang dilakukan blok kode, itu adalah bau kode yang menunjukkan bahwa Anda harus mengubah blok ini menjadi sebuah fungsi dengan nama deskriptif.

Jadi, bukannya

// fixed bug XXXXX on 10/9/2012

Anda mungkin memiliki komentar yang mengatakan

// doing X, because otherwise Y will break.

atau

// doing X, because doing Y is 10 times slower.

Gunakan alat terbaik untuk pekerjaan itu. Sistem kontrol versi Anda harus menjadi alat terbaik untuk merekam ketika perbaikan bug dan CR dibuat: ia secara otomatis mencatat tanggal dan siapa yang membuat perubahan; tidak pernah lupa menambahkan pesan (jika Anda mengonfigurasinya untuk meminta pesan komit); tidak pernah membuat anotasi pada baris kode yang salah atau secara tidak sengaja menghapus komentar. Dan jika sistem kontrol versi Anda sudah melakukan pekerjaan yang lebih baik daripada komentar Anda, itu konyol untuk menduplikasi pekerjaan dengan menambahkan komentar.

Keterbacaan kode sumber sangat penting. Basis kode yang penuh dengan komentar yang memberikan riwayat lengkap dari setiap perbaikan bug dan CR yang dibuat tidak akan bisa dibaca sama sekali.

Tetapi jangan melewatkan komentar sepenuhnya: Komentar yang baik (tidak secara sembarang mendokumentasikan setiap awal / berhenti / deskripsi / solusi dari setiap perbaikan bug dan CR) meningkatkan keterbacaan kode. Misalnya, untuk sedikit kode yang rumit atau tidak jelas yang Anda tambahkan untuk memperbaiki bug, komentar pada formulir // fix ISSUE#413memberi tahu orang-orang di mana menemukan lebih banyak informasi dalam pelacak masalah Anda adalah ide yang bagus.

Komentar dalam kode adalah tentang apa kode itu pada saat itu. Mengambil snapshot pada waktu tertentu tidak boleh merujuk ke versi kode yang lama (atau lebih buruk, di masa depan).

Komentar dalam VCS adalah tentang bagaimana kode telah berubah. Mereka harus membaca sebagai cerita tentang perkembangan.

Sekarang, setiap perubahan harus menyertakan komentar? dalam banyak kasus, ya. Satu-satunya pengecualian yang saya bayangkan adalah ketika perilaku yang diharapkan sudah didokumentasikan tetapi bukan yang Anda dapatkan, karena bug. Memperbaikinya membuat komentar yang ada lebih tepat, sehingga tidak perlu diubah. Bug itu sendiri harus didokumentasikan dalam sejarah tiket dan komentar komit, tetapi hanya dalam kode jika kode itu terlihat aneh. Dalam hal ini, a // make sure <bad thing> doesn't happensudah cukup.

Salah satu jenis komentar yang sangat saya hargai adalah:

// Ini diterapkan untuk Aturan Bisnis 5 dari Proposal 2

atau apa pun yang Anda gunakan untuk memenuhi kebutuhan Anda.

Ini memiliki dua keuntungan, satu memungkinkan Anda menemukan alasan Anda menerapkan algoritma yang diberikan tanpa mencari dan yang lain adalah akan membantu Anda berkomunikasi dengan insinyur non-perangkat lunak yang bekerja pada / membuat dokumen persyaratan.

Ini mungkin tidak membantu dengan tim yang lebih kecil tetapi jika Anda memiliki analis yang mengembangkan kebutuhan Anda, itu bisa sangat berharga.

Petunjuk Anda benar ketika mereka mengatakan bahwa komentar adalah praktik pemrograman yang baik, namun ada pengecualian. Menambahkan komentar untuk setiap perubahan yang Anda lakukan adalah salah satunya. Dan Anda benar dengan mengatakan bahwa ini harus menjadi milik sistem kontrol versi. Jika Anda harus menyimpan komentar ini di satu tempat, maka VCS adalah jalan yang harus ditempuh. Komentar dalam kode sumber cenderung menjadi tua dan tidak terawat. Tidak ada komentar yang jauh lebih baik daripada komentar buruk. Yang tidak Anda inginkan adalah memiliki komentar di kedua tempat (dalam kode dan VCS) yang tidak sinkron. Tujuannya adalah untuk menjaga hal-hal KERING dengan memiliki satu sumber kebenaran untuk perubahan kode.

Selain apa yang dikatakan orang lain, pertimbangkan apa yang terjadi jika perubahan memiliki efek riak di seluruh sistem. Katakanlah Anda membuat refactor bagian dari antarmuka inti dalam proses penerapan permintaan perubahan - perubahan semacam itu dapat dengan mudah menyentuh persentase besar dari file kode sumber dalam perangkat lunak yang tidak sepele dengan jumlah perubahan sepele apa pun (kelas atau perubahan nama metode). Apakah Anda harus membaca setiap file yang disentuh oleh operasi seperti itu untuk secara manual membuat catatan dengan komentar seperti itu, daripada mengandalkan VCS yang melakukan semuanya secara otomatis? Dalam satu kasus Anda melihat pekerjaan sedikit lebih dari lima menit dengan alat refactoring yang layak diikuti oleh kompilasi ulang untuk memastikan tidak ada yang merusak bangunan, sedangkan yang lain dapat dengan mudah berkembang menjadi pekerjaan sehari. Untuk manfaat spesifik apa?

Juga pertimbangkan apa yang terjadi ketika Anda memindahkan bagian dari kode. Salah satu pengembang basis data yang bekerja sama dengan saya adalah di kamp "setiap baris SQL harus diberi catatan dengan revisi yang mana itu diubah, dan kami akan melakukan revisi sejarah terpisah untuk setiap file karena dengan demikian lebih mudah untuk melihat siapa yang mengubah apa kapan dan mengapa ". Itu bekerja agak agak oke ketika perubahan itupada urutan mengubah satu baris. Itu tidak berfungsi dengan baik ketika, seperti yang saya lakukan baru-baru ini untuk memperbaiki masalah kinerja yang serius, Anda memecahkan bagian dari kueri yang lebih besar memperkenalkan tabel sementara, lalu mengubah urutan beberapa pertanyaan agar lebih sesuai dengan aliran kode baru. Memang, perbedaan terhadap versi sebelumnya sebagian besar tidak ada artinya karena dikatakan sekitar dua pertiga dari file telah berubah, tetapi komentar check-in juga sesuatu seperti "reorganisasi besar untuk memperbaiki masalah kinerja". Pada saat Anda melihat dua versi secara manual, sudah cukup jelas bahwa sebagian besar benar-benar sama, hanya bergerak. (Dan butuh prosedur tersimpan yang dipertanyakan dari secara teratur mengambil lebih dari setengah menit untuk mengeksekusi, menjadi beberapa detik. Pada saat itu,

Dengan sedikit pengecualian, pelacakan perubahan dan referensi masalah adalah pekerjaan VCS, IMNSHO.

Saya biasanya mengikuti aturan ini: jika perubahannya jelas dan kode yang dihasilkan tidak menimbulkan pertanyaan, tidak mengembalikan atau secara substansial mengubah perilaku sebelumnya dengan cara yang substansial - kemudian serahkan ke VCS untuk melacak nomor bug dan informasi perubahan lainnya.

Namun, jika ada perubahan yang tidak jelas, yang mengubah logika - terutama secara substansial mengubah logika yang dilakukan oleh orang lain dengan cara yang tidak jelas - mungkin sangat bermanfaat untuk menambahkan sesuatu seperti "perubahan ini adalah untuk melakukan ini dan itu karena bug # 42742 ". Dengan cara ini ketika seseorang melihat kode dan bertanya-tanya "mengapa ini ada di sini? Ini terlihat aneh" dia memiliki beberapa panduan tepat di depannya dan tidak harus melakukan penyelidikan melalui VCS. Ini juga mencegah situasi di mana orang merusak perubahan orang lain karena mereka terbiasa dengan keadaan kode lama tetapi tidak menyadari bahwa itu telah diubah sejak itu.

Komentar terkait kontrol versi tidak termasuk dalam file sumber. Mereka hanya menambahkan kekacauan. Karena mereka kemungkinan harus diletakkan di tempat yang sama (seperti blok komentar di bagian atas file), mereka akan menyebabkan konflik gangguan komentar-saja ketika cabang paralel digabungkan.

Setiap informasi pelacakan yang dapat ditarik keluar dari kontrol versi tidak boleh diduplikasi dalam tubuh kode. Itu berlaku untuk ide-ide konyol seperti kata kunci checkout RCS suka $Log$dan sejenisnya.

Jika kode pernah melakukan perjalanan di luar ruang lingkup sistem kontrol versi, jejak komentar tentang sejarahnya kehilangan konteks dan karenanya sebagian besar nilainya. Untuk memahami deskripsi perubahan dengan benar, kami memerlukan akses ke revisi, sehingga kami dapat melihat perbedaan dengan versi sebelumnya.

Beberapa file lama di kernel Linux memiliki blok komentar sejarah besar. Tanggal kembali ke saat tidak ada sistem kontrol versi, hanya tarbal dan tambalan.

Komentar dalam kode harus minimal dan akurat. Menambahkan cacat / mengubah informasi tidak berharga. Anda harus menggunakan kontrol versi untuk itu. Beberapa kontrol Versi waktu menyediakan cara perubahan yang sedikit lebih baik- Kami menggunakan ClearCase UCM; Aktivitas UCM dibuat berdasarkan angka cacat, ubah area dll (mis. Defect29844_change_sql_to_handle_null).

Komentar terinci lebih disukai di komentar lapor-masuk.

Saya lebih suka menyertakan memberikan rincian tentang informasi latar belakang, rincian solusi TIDAK dilaksanakan karena beberapa efek samping.

Pramagic Programmer dan CleanCode mengarah ke pedoman berikut

Simpan pengetahuan tingkat rendah dalam kode, di mana kode itu berada, dan simpan komentar untuk penjelasan tingkat tinggi lainnya.