Saya biasanya menganggap komentar seperti itu sebagai praktik buruk dan saya pikir informasi semacam ini milik log komit SCM. Itu hanya membuat kode lebih sulit untuk dibaca dalam banyak kasus.
Namun , saya masih sering melakukan hal seperti ini untuk jenis pengeditan tertentu.
Kasus 1 - Tugas
Jika Anda menggunakan IDE seperti Eclipse, Netbeans, Visual Studio (atau memiliki cara melakukan pencarian teks pada basis kode Anda dengan yang lain), mungkin tim Anda menggunakan beberapa "tag komentar" atau "tag tugas" tertentu. Dalam hal ini hal ini dapat bermanfaat.
Saya akan dari waktu ke waktu, ketika meninjau kode, menambahkan sesuatu seperti yang berikut:
// TOREVIEW: [2010-12-09 haylem] marking this for review because blablabla
atau:
// FIXME: [2010-12-09 haylem] marking this for review because blablabla
Saya menggunakan tag tugas khusus yang berbeda yang dapat saya lihat di Eclipse dalam tampilan tugas untuk ini, karena memiliki sesuatu di log komit adalah hal yang baik tetapi tidak cukup ketika Anda memiliki eksekutif yang meminta Anda dalam rapat ulasan mengapa perbaikan bug XY benar-benar dilupakan dan lolos. Jadi pada masalah yang mendesak atau potongan kode yang benar-benar dipertanyakan, ini berfungsi sebagai pengingat tambahan (tapi biasanya saya akan membuat komentar singkat dan memeriksa log komit karena ITULAH pengingat di sini untuk, jadi saya tidak mengacaukan kode juga banyak).
Kasus 2 - Patch Libs Pihak Ketiga
Jika produk saya perlu mengemas sepotong kode pihak ke-3 sebagai sumber (atau pustaka, tetapi dibuat ulang dari sumber) karena perlu ditambal karena suatu alasan, kami mendokumentasikan tambalan itu dalam dokumen terpisah di mana kami mencantumkan "peringatan" tersebut. untuk referensi di masa mendatang, dan kode sumber biasanya akan berisi komentar yang mirip dengan:
// [PATCH_START:product_name]
// ... real code here ...
// [PATCH_END:product_name]
Kasus 3 - Perbaikan yang Tidak Jelas
Yang ini sedikit lebih kontroversial dan lebih dekat dengan apa yang diminta oleh seniormu.
Dalam produk yang saya kerjakan saat ini, kami kadang-kadang (jelas bukan hal yang umum) memiliki komentar seperti:
// BUGFIX: [2010-12-09 haylem] fix for BUG_ID-XYZ
Kami hanya melakukan ini jika perbaikan bug tidak jelas dan kode terbaca tidak normal. Ini dapat menjadi contoh untuk kebiasaan browser misalnya, atau perbaikan CSS yang tidak jelas yang perlu Anda terapkan hanya karena ada bug dokumen dalam suatu produk. Jadi secara umum kami akan menautkannya ke repositori masalah internal kami, yang kemudian akan berisi alasan terperinci di balik perbaikan bug dan petunjuk ke dokumentasi bug produk eksternal (katakanlah, penasihat keamanan untuk cacat Internet Explorer 6 yang terkenal, atau sesuatu seperti itu).
Tetapi seperti yang disebutkan, itu sangat jarang. Dan berkat tag tugas, kita dapat secara teratur menjalankan ini dan memeriksa apakah perbaikan aneh ini masih masuk akal atau dapat dihapus (misalnya, jika kita menjatuhkan dukungan untuk produk kereta yang menyebabkan bug di tempat pertama).
Ini hanya dalam: Contoh kehidupan nyata
Dalam beberapa kasus, ini lebih baik daripada tidak sama sekali :)
Saya baru saja menemukan kelas perhitungan statistik yang sangat besar di basis kode saya, di mana komentar header dalam bentuk changelog dengan yadda yadda yang biasa: reviewer, date, bug ID.
Pada awalnya saya berpikir untuk menghapus tetapi saya perhatikan ID bug tidak hanya tidak cocok dengan konvensi pelacak masalah kami saat ini tetapi juga tidak cocok dengan pelacak yang digunakan sebelum saya bergabung dengan perusahaan. Jadi saya mencoba membaca kode dan mendapatkan pemahaman tentang apa yang dilakukan kelas (bukan menjadi ahli statistik) dan juga mencoba menggali laporan cacat ini. Ketika itu terjadi, mereka cukup penting dan akan mengatur kehidupan orang berikutnya untuk mengedit file tanpa mengetahui tentang mereka cukup mengerikan, karena berurusan dengan masalah presisi kecil dan kasus khusus berdasarkan persyaratan yang sangat spesifik yang dipancarkan oleh pelanggan yang berasal saat itu . Intinya, jika ini belum ada di sana, saya tidak akan tahu. Jika mereka tidak ada di sana DAN saya memiliki pemahaman yang lebih baik tentang kelas,
Terkadang sulit untuk melacak persyaratan yang sangat lama seperti ini. Pada akhirnya apa yang saya lakukan masih menghapus header, tetapi setelah menyelinap di blok komentar sebelum setiap fungsi memberatkan menjelaskan mengapa ini "aneh" perhitungan karena mereka permintaan khusus.
Jadi dalam hal itu saya masih menganggap ini sebagai praktik yang buruk, tetapi anak laki-laki itu saya senang pengembang asli setidaknya menempatkan mereka di! Akan lebih baik untuk mengomentari kode dengan jelas sebagai gantinya, tapi saya kira itu lebih baik daripada tidak sama sekali.