Ide bagus untuk memasukkan nomor bug dalam komentar di awal file sumber? [Tutup]

Apakah ini praktik yang baik untuk memasukkan nomor bug dalam file itu sendiri di dalam komentar header?

Komentar akan terlihat seperti ini:

 MODIFIED    (MM/DD/YY)
 abc 01/21/14 - Bug 17452317 - npe in drill across in dashboard edit mode

 cde 01/17/14 - Bug 2314558  - some other error description

Tampaknya membantu, tetapi apakah itu dianggap praktik yang buruk?

Saya telah melihat ini dilakukan sebelumnya, baik secara manual oleh penulis dan secara otomatis oleh skrip dan pemicu terintegrasi dengan sistem kontrol versi untuk menambahkan penulis, komentar check-in, dan informasi tanggal ke file.

Saya pikir kedua metode ini cukup mengerikan karena dua alasan utama. Pertama, ini menambahkan kekacauan dan kebisingan ke file, terutama karena usia komentar ini dan menjadi tidak relevan dengan keadaan file saat ini. Kedua, ini adalah duplikat informasi dari apa yang sudah dipertahankan dalam sistem kontrol versi, dan jika Anda menggunakan sistem kontrol versi modern yang mendukung perubahan-set, maka itu sebenarnya kehilangan informasi tentang perubahan.

Jika ada, pertimbangkan integrasi dengan sistem pelacakan cacat Anda. Beberapa alat memungkinkan Anda menautkan nomor ID tugas atau cacat dalam komentar check-in ke item di alat pelacakan. Jika Anda memiliki semua cacat, permintaan tambahan, dan tugas kerja di alat ini, Anda dapat menyediakan tautan seperti itu. Tentu saja, ini datang dengan kelemahan dari ketergantungan pada alat-alat untuk proyek tersebut.

Tepat ada satu kasus di mana saya akan melakukan ini, yaitu sebagai bagian dari peringatan untuk programmer masa depan: "Jangan panggil fungsi di foo()sini secara langsung; ini telah menyebabkan bug # 1234, yaitu ...", dan kemudian deskripsi singkat tentang bug mengikuti.

Dan jika kode telah berubah sedemikian rupa sehingga tidak ada godaan untuk menelepon foo()secara langsung, hapus komentar itu. Itu hanya akan mengganggu dan meledakkan kode.

Ini adalah praktik yang sama sekali mengerikan. Ini menambah upaya untuk mencapai efek duplikasi murni; dengan kata lain, satu-satunya hal yang ditambahkan daripada hanya menggunakan log komit adalah kemungkinan menciptakan inkonsistensi. File sumber Anda menjadi berantakan dengan jumlah barang tak terbatas yang tidak pernah Anda lihat.

Satu-satunya sisi positif yang saya dapat membedakan sama sekali adalah bahwa Anda dapat merekonstruksi riwayat sumber tanpa akses ke kontrol versi, misalnya ketika mempelajari hasil cetak. Tetapi sangat sedikit orang yang cukup kompeten untuk mengikuti seluk-beluk pengembangan perangkat lunak, sementara secara bersamaan tidak dapat memahami kontrol versi.

Tidak.

Itulah yang dilakukan orang sebelum mereka menggunakan sistem kontrol versi (yaitu ketika kode sumber hanya cadangan di zipfiles).

Ini, IMHO, ide yang sangat buruk. Setelah revisi angka 100, Anda akan memiliki 90% komentar dan 10% kode. Saya tidak akan menganggap itu bersih dan mudah dibaca.

Satu-satunya poin dalam hal ini yang saya lihat adalah ketika Anda harus menukar kode Anda antara SCC dan, untuk alasan apa pun, Anda tidak dapat mentransfer riwayat antara kedua sistem (tetapi bahkan ketika Anda menyimpan komentar histori dengan cara itu, Anda akan kehilangan histori diff juga, jadi menyimpan komentar hanya akan membantu Anda sedikit).

Saya melihat bahwa semua orang menentang gagasan itu dan memberikan alasan historis (era kontrol sebelum sumber) mengapa orang melakukannya.

Namun, di perusahaan saya saat ini, pengembang database mengikuti praktik ini dan mereka juga menandai nomor bug di sekitar potongan kode. Saya kadang-kadang menemukan ini membantu ketika Anda melihat bug dalam kode dan Anda dapat langsung menemukan perbaikan bug yang menyebabkan masalah ini. Jika kami tidak memiliki informasi itu dalam paket basis data saya, tentu tidak akan mudah untuk menemukan akar penyebab implementasi itu.

Ya, itu mengacaukan kode, tetapi membantu dalam menemukan alasan mengapa potongan kode itu ada.

Salah satu poin dalam tes Joel adalah

Apakah Anda memiliki basis data bug?

Informasi seperti itu mungkin disimpan dalam database bug jika Anda pikir itu penting, tetapi itu hanya akan berisik dalam komentar.

Saya pikir Anda memiliki dua masalah di sini. Pertama, mengapa Anda harus semata-mata mengandalkan perbedaan ketika kebanyakan sistem memungkinkan Anda untuk memasukkan komentar revisi? Seperti komentar kode yang baik, Anda menemukan mengapa perubahan itu dilakukan dan bukan hanya perubahan itu sendiri.

Kedua, jika Anda memiliki kemampuan ini, jadikan itu praktik yang baik untuk menempatkan semuanya di tempat yang sama. Tidak perlu melihat-lihat file untuk mencari baris kode yang tidak lagi diperlukan. Komentar di dalam kode kerja ada untuk memberi tahu Anda mengapa dikodekan dengan cara ini.

Setelah Anda mempraktikkannya, kebiasaan yang terbentuk membuat basis kode lebih mudah dikerjakan untuk semua orang.

Pelacakan bug dan fitur terkait beserta alasan Anda mengubah file ini, dapat memberi Anda gambaran tentang seberapa dalam Anda perlu menggali sejarah dan mungkin melihat perbedaan. Saya punya permintaan untuk "Ubah kembali ke formula asli." Saya tahu benar ke mana harus pergi dalam sejarah revisi dan hanya mengulas satu atau dua perbedaan.

Secara pribadi, kode yang dikomentari terlihat seperti pekerjaan yang sedang berlangsung untuk masalah yang sedang diselesaikan dengan coba-coba. Dapatkan kekacauan ini dari kode produksi. Mampu menyelinap dengan mudah baris kode masuk dan keluar hanya membuatnya lebih mudah untuk bingung.

Jika Anda tidak memiliki VCS dengan pesan komit, dan tidak ada sistem pelacakan bug dengan opsi bagi Anda untuk meninggalkan komentar, itu satu opsi, dan bukan yang optimal, untuk melacak perubahan.
Lebih baik memiliki spreadsheet dengan informasi itu, atau jika Anda berada di lingkungan tanpa "kemewahan" seperti itu, file teks berada di dekat sumber Anda.
Tapi saya akan sangat menyarankan jika Anda berada dalam lingkungan seperti itu untuk mulai membangun sebuah kasus untuk berinvestasi dalam sistem pelacakan bug VCS :)

Ingatlah ini - kode sering kali lebih panjang daripada alat yang mendukungnya. Dengan kata lain, pelacak masalah, kontrol versi, dan semua skrip lainnya akan berevolusi selama pengembangan. Informasi hilang.

Sementara saya setuju, kekacauan file itu mengganggu, membuka file dan memahami sejarahnya tanpa menggunakan alat, selalu sangat membantu - terutama jika saya menjaga kode.

Secara pribadi, saya pikir ada ruang untuk alat dan in-code log.

Aku tahu Git tidak melakukan hal ini dan jawaban sederhana adalah "mengapa di bumi akan itu pergi ke sana?"

Ini desain yang kurang modular pada umumnya. Di bawah solusi ini, sekarang file adalah beberapa campuran antara konten dan meta-data. Amazon S3 adalah contoh lain dari layanan untuk menyimpan file yang tidak menambahkan materi depan YAML atau sejenisnya ke file.

Setiap pengguna file harus memprosesnya melalui sistem kontrol versi terlebih dahulu. Ini adalah kopling ketat, mis. IDE favorit Anda akan rusak jika tidak mendukung VCS Anda.

Tidak, ini bukan praktik yang baik untuk melacak perbaikan bug Anda sebagai komentar dalam kode. Ini hanya menghasilkan kekacauan.

Saya juga akan mengatakan hal yang sama untuk pesan hak cipta yang Anda sebutkan. Jika tidak ada orang di luar perusahaan Anda yang akan melihat kode ini, tidak ada alasan untuk memasukkan pesan hak cipta.

Jika Anda menggunakan perangkat lunak pelacakan versi ( Git , SVN , dll.), Maka Anda harus memasukkan catatan itu dalam pesan komit Anda. Tidak ada yang ingin menggali melalui header setiap file kode untuk menghasilkan catatan rilis atau melihat ikhtisar tentang perubahan apa yang dilakukan. Log perubahan ini semua harus disimpan bersama, baik dalam riwayat pelacakan versi Anda, pelacak cacat Anda, atau keduanya.

Jika Anda mencari bacaan yang baik tentang hal ini, saya sarankan bab empat dari Kode Bersih .

Saya pikir ada unsur-unsur lain dalam diskusi ini yang sering dilupakan tetapi adalah kasus di mana beberapa komentar revisi cepat untuk sebuah tim.

Ketika bekerja di lingkungan tim dengan basis kode bersama dan di mana beberapa anggota tim berpotensi bekerja di bidang kode yang sama, menempatkan komentar revisi singkat dalam lingkup yang benar (metode atau kelas) yang mengindikasikan perubahan dibuat dapat sangat berguna untuk cepat menyelesaikan konflik merger atau checkin.

Demikian juga, ketika bekerja di lingkungan di mana beberapa (fitur) cabang terlibat, akan memudahkan orang ketiga (membangun master) untuk mengidentifikasi apa yang harus dilakukan untuk menyelesaikan potensi konflik.

Kapan pun Anda harus menjauh dari IDE dan bertanya kepada seseorang mengapa mereka mengubah sesuatu, itu mengganggu produktivitas kedua anggota tim. Catatan cepat dalam lingkup yang benar dapat membantu mengurangi atau menghilangkan sebagian besar gangguan ini.

Setiap informasi bug yang terkait langsung dengan sepotong kode, menjadi tidak relevan ketika integritas dari seluruh perubahan dimodifikasi oleh perbaikan yang berurutan.

Dulu biasa untuk menambahkan info dalam ringkasan fungsi ketika kami harus bergantung pada alat eksternal (katakanlah javadocs) untuk membuat catatan rilis dari kode. Sebagian besar tidak berguna atau berlebihan dengan alat kontrol versi modern.

Itu hanya bisa masuk akal sebagai komentar dalam sepotong kode yang sangat modular, jika seseorang harus menggunakan beberapa kode yang tidak jelas atau non-bintang yang pengembang masa depan akan tergoda untuk berubah - tidak menyadari alasan di baliknya - seperti dalam pemecahan masalah dengan bug / kekurangan perpustakaan.

Saya pasti tidak akan menaruh informasi seperti itu di awal file - biasanya hal seperti itu termasuk dalam sistem tiket.

Namun ada beberapa kasus di mana referensi ke sistem tiket dan / atau dokumentasi lainnya masuk akal. Misalnya, jika ada penjelasan panjang tentang desain, atau deskripsi alternatif. Atau informasi cara menguji sesuatu, atau penjelasan mengapa itu dilakukan persis seperti itu. Jika itu pendek, itu milik file itu sendiri; jika panjang dan / atau sekitar gambar yang lebih besar, Anda mungkin ingin meletakkannya di tempat lain dan merujuknya.

Proyek tempat saya ditugaskan saat ini memiliki daftar nomor bug jenis ini pada awal setiap file; namun, tidak ada pengembang yang masih dalam proyek menambahkannya lagi. Sebagian besar dari mereka berpikir itu adalah pemborosan ruang yang tidak berguna, karena jauh lebih rendah daripada pelacakan bug yang dilakukan ke file menggunakan sistem kontrol versi kami.

Dalam file kritis tertentu yang telah mengalami banyak perbaikan dan peningkatan, daftar ini menjadi sangat besar sehingga Anda harus menggulir melewatinya untuk sampai ke kode. Ketika memahami daftar-daftar ini dapat menghasilkan beberapa kesalahan positif ketika judul bug pendek atau deskripsi singkat dicantumkan dengan masing-masing.

Singkatnya, daftar ini paling tidak berguna dan paling buruk, pemborosan ruang besar-besaran yang membuat kode lebih sulit untuk dicari dan ditemukan.