Pengembang senior di toko kami bersikeras bahwa setiap kali kode dimodifikasi, programmer yang bertanggung jawab harus menambahkan komentar sebaris yang menyatakan apa yang dia lakukan. Komentar-komentar ini biasanya terlihat seperti// YYYY-MM-DD <User ID> Added this IF block per bug 1234.

Kami menggunakan TFS untuk kontrol revisi, dan menurut saya komentar semacam ini jauh lebih tepat sebagai catatan masuk daripada kebisingan inline. TFS bahkan memungkinkan Anda untuk mengaitkan check-in dengan satu atau lebih bug. Beberapa file kelas kami yang lebih lama dan sering dimodifikasi sepertinya memiliki rasio komentar-ke-LOC yang mendekati 1: 1. Bagi saya, komentar-komentar ini membuat kode lebih sulit dibaca dan menambah nilai nol.

Apakah ini praktik standar (atau paling tidak umum) di toko lain?

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.

Kami menggunakan praktik itu untuk file yang tidak di bawah kontrol versi. Kami memiliki program RPG yang berjalan pada mainframe, dan terbukti sulit untuk melakukan lebih dari mendukungnya.

Untuk kode sumber versi, kami menggunakan catatan check-in. Saya pikir di situlah tempatnya, bukan mengacaukan kode. Bagaimanapun, ini metadata.

Kami dulu memiliki praktik ini di toko SW di mana manajer kami bersikeras bahwa ia ingin dapat membaca file kode di atas kertas dan mengikuti riwayat revisi mereka. Tak perlu dikatakan, saya tidak ingat kejadian konkret ketika dia benar-benar melihat cetakan file sumber: - /

Untungnya, manajer saya sejak itu telah lebih mengetahui tentang apa yang dapat dilakukan sistem kontrol versi (saya harus menambahkan bahwa kami menggunakan SourceSafe di toko pertama itu). Jadi saya tidak menambahkan metadata versi ke dalam kode.

Biasanya tidak diperlukan jika SCM dan IDE Anda memungkinkan Anda untuk menggunakan fitur "tampilkan anotasi" (sebutkan ini di Eclipse), Anda dapat dengan mudah melihat komit yang mengubah sepotong kode, dan komentar komit harus memberi tahu siapa dan mengapa.

Satu-satunya saat saya memberikan komentar seperti ini dalam kode adalah jika itu adalah kode yang sangat aneh yang dapat menyebabkan seseorang kebingungan di masa depan, saya akan berkomentar singkat dengan nomor bug sehingga mereka dapat pergi ke laporan bug dan membaca secara rinci tentang hal itu.

Jelas, komentar semacam itu hampir pasti tidak benar dari waktu ke waktu; jika Anda mengedit satu baris dua kali, apakah Anda menambahkan dua komentar? Kemana mereka pergi? Jadi proses yang lebih baik adalah mengandalkan alat Anda.

Ini adalah tanda bahwa, untuk alasan apa pun, pengembang senior tidak dapat mengandalkan proses baru untuk melacak perubahan dan menghubungkan perubahan ke sistem pelacakan masalah. Anda harus mengatasi ketidaknyamanan ini untuk menyelesaikan konflik.

Anda perlu memahami mengapa dia tidak bisa mengandalkannya. Apakah ini kebiasaan lama? Pengalaman buruk dengan sistem SCM? Format presentasi yang tidak berhasil untuknya? Mungkin dia bahkan tidak tahu tentang alat seperti 'git menyalahkan' dan pandangan timeline Perforce (yang pada dasarnya menunjukkan ini, meskipun mungkin tidak menunjukkan masalah apa yang memicu perubahan).

Tanpa memahami alasannya untuk persyaratan, Anda tidak akan dapat meyakinkannya.

Saya bekerja pada produk Windows yang berumur 20+ tahun. Kami memiliki praktik serupa yang sudah ada sejak lama. Saya tidak bisa menghitung berapa kali latihan ini menghemat daging saya.

Saya setuju bahwa beberapa hal berlebihan. Dulu pengembang menggunakan praktik ini untuk mengomentari kode. Ketika saya meninjau ini, saya memberitahu mereka untuk melanjutkan dan menghapus kode, dan komentar itu tidak perlu.

Tetapi, sering kali, Anda bisa melihat kode yang telah ada sekitar satu dekade dan dimodifikasi oleh 20 pengembang tetapi tidak pernah dire-refactored. Semua orang sudah lama melupakan semua detail persyaratan yang ada dalam kode asli, apalagi perubahan, dan tidak ada dokumentasi yang dapat diandalkan.

Sebuah komentar dengan nomor cacat memberi saya tempat untuk mencari asal kode.

Jadi, ya, sistem SCM melakukan banyak hal, tetapi tidak semuanya. Perlakukan ini seperti yang Anda lakukan komentar lain, dan tambahkan di mana pun perubahan signifikan dibuat. Pengembang melihat kode Anda 5+ tahun dari bagaimana akan berterima kasih.

Menyebutkan setiap perubahan dalam komentar tidak ada gunanya jika Anda memiliki VCS. Menyebutkan bug tertentu atau catatan penting lainnya yang terkait dengan jalur tertentu berguna. Suatu perubahan dapat mencakup banyak baris yang diubah, semuanya di bawah pesan komit yang sama.

Bukannya aku bisa tahu.

Saya melakukan splatter TODO dalam kode saya saat saya melanjutkan, dan tujuannya adalah menghapusnya pada waktu review.