Apakah baik menyimpan komentar perbaikan bug di dalam kode?

Tim saya menggunakan huruf besar sebagai kontrol versi. Proyek yang saya kerjakan tidak dimulai 7-8 tahun yang lalu. Selama masa hidup proyek kami memiliki beberapa rilis paket layanan perbaikan bug dll. Masalah dilacak menggunakan sistem pelacakan bug dan sebagian besar orang yang bekerja pada perbaikan bug mengikuti rutinitas melampirkan komentar di MULAI / AKHIR blok dengan tanggal, penulis, bug-id dll.

Saya merasa ini sangat tidak relevan dan membuat kode berantakan dan tidak nyaman untuk dipelihara dan ini adalah hal-hal yang harus menjadi bagian dari komentar / label check-in dll, di mana kita dapat menyimpan informasi siklus hidup tambahan dari produk kerja.

Apa praktik terbaik yang harus diikuti?

Beberapa pengulas kode bersikeras untuk mengeluarkan komentar tentang bug dan perbaikan untuk memudahkan hidup mereka. Dalam pemahaman saya, mereka harus meninjau file dengan memetakannya ke tampilan dan mendapatkan log perubahan cabang dan memeriksanya. Akan sangat membantu jika saya bisa mendapatkan beberapa praktik terbaik tentang pengiriman kode yang diperbarui untuk ditinjau.

Masalah dengan menambahkan perbaikan bug sebagai komentar pada kode adalah, Anda tidak mendapatkan cerita lengkap. Jika saya melihat sepotong baik-baik saja kode tagged "ini adalah fix untuk bug bla ", reaksi pertama saya akan mengatakan "jadi apa?". Kode itu ada, itu berfungsi. Satu-satunya hal yang perlu saya ketahui untuk mempertahankan kode adalah komentar yang memberi tahu saya apa yang dilakukannya.

Praktik yang lebih baik adalah menambahkan referensi perbaikan bug di log komit SCM. Dengan begitu, Anda melihat apa bug itu, di mana bug itu diperkenalkan, dan bagaimana bug itu diperbaiki. Selain itu, ketika waktu untuk rilis tiba, Anda cukup mengekstrak log SCM, dan menambahkan poin-poin yang menyatakan bahwa ada bug, dan itu diperbaiki. Jika cabang atau versi lain memperkenalkan bug yang sama, mudah untuk menemukan perbaikannya, dan mengajukan kembali jika memang hal yang sama.

Setelah mengatakan semua ini, saya juga setuju dengan jawaban Charles. Jika alasan untuk sepotong kode tidak jelas, tentu saja, beri tahu pengelola bahwa kode ada karena suatu alasan, dan harus diperlakukan dengan hati-hati.

Latihan yang paling buruk. Saya tidak akan mengatakan itu tidak boleh dilakukan. Kadang-kadang Anda mengalami sesuatu seperti bug di API eksternal yang harus Anda atasi. Solusi ini dapat benar-benar mati otak jika Anda tidak tahu tentang bug yang mendasarinya. Dalam hal ini mungkin ide yang baik untuk mendokumentasikan bug dalam kode sehingga rekan kerja atau diri Anda nanti tidak mencoba untuk "memperbaiki" kode mati otak yang jelas.

Latihan yang buruk. Komentar akan keluar dari tanggal dan mengacaukan kode. Informasi ini masih tersedia dalam riwayat versi sistem SCC Anda jika diperlukan.

Kedengarannya seperti latihan yang buruk. Bagaimana jika organisasi Anda memutuskan untuk bermigrasi ke sistem pelacakan bug lain? Jangan ikat produk Anda terlalu erat dengan alat yang sedang Anda gunakan. Alih-alih merujuk ke bug ID tertentu, dan alasan mengapa kode itu terlihat tidak jelas, memotivasi keputusan desain Anda dengan komentar dalam kode.

Reaksi pertama saya adalah jangan ulangi diri Anda sendiri sehingga keluar dari kode dan masuk ke log SCM. Kami telah melakukan diskusi serupa di sini tentang komentar revisi untuk fungsi, nama penulis dan tanggal pembuatan untuk file dan fungsi. Di masa lalu (sebelum SCM digunakan) semua informasi ini disimpan dalam file untuk dapat merekonstruksi evolusi file.

Sekitar setengah dari pengembang menginginkan informasi ini agar dapat memiliki semua informasi di satu tempat (ini memicu mereka untuk mencari perubahan dalam SCM). Setengah lainnya dari pengembang tidak memulai pencarian mereka untuk petunjuk tentang apa yang berubah di coe, tetapi dari SCM sehingga mereka tidak memerlukan informasi dalam kode. Kami belum memutuskan apa yang harus dilakukan dengan komentar-komentar itu. Ini sangat tergantung pada cara orang bekerja dan beberapa orang sangat keras kepala meninggalkan metode yang dikenal. Hal yang sama tentang mengomentari blok kode dan meninggalkannya di dalam kode selamanya.

Hanya untuk menambah apa yang Dyaster et al. telah mengatakan, meskipun JIRA memiliki kemampuan yang sangat bagus untuk menampilkan perubahan yang terkait dengan perbaikan bug, tempat terbaik mutlak untuk mendokumentasikan perbaikan bug adalah dalam kasus uji. Jika kode tidak jelas tanpa komentar yang menunjukkan bug apa yang diperbaiki, itu "bau kode". Yang mengatakan, jika Anda tidak punya waktu untuk membersihkan bau, komentar harus merujuk pada test case, di mana seharusnya jauh lebih jelas mengapa kodenya melakukan apa yang dilakukannya. Jika Anda tidak punya waktu untuk menulis test case yang menjelaskan perbaikan bug, maka bug tersebut belum benar-benar diperbaiki, hanya ditunda.

Saya setuju dengan menambahkan id perbaikan bug dalam pesan komit, dan tidak di dalam kode itu sendiri. Pelacak bug yang secara otomatis mengikis pesan komit untuk id bug sangat berguna.

Selain itu, Anda dapat menggunakan perintah menyalahkan / membubuhi keterangan / pujian dari sistem kontrol versi Anda untuk membantu mengganti komentar ini. Kemudian, ketika Anda menjalankan sesuatu seperti:

vcs blame file.ext

Anda dapat melihat informasi yang berguna, biasanya termasuk siapa yang mengubah setiap baris, ketika mereka mengubahnya, dan id komit. Dari id komit, Anda bisa mendapatkan pesan lengkap, yang harus menyertakan id bug.

Sistem VCS yang baik akan membuat Anda mengabaikan spasi ketika menghitung siapa yang mengubah garis.

Saya tidak tahu apa yang dimiliki Clear Case untuk fitur ini.