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


40

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?


23
Pertanyaan yang saya ajukan adalah "Apa yang dapat Anda lakukan dengan nomor bug tertanam yang belum dapat Anda lakukan dengan database bug Anda?" Saya tidak bisa memikirkan kasus penggunaan yang sebenarnya.
M. Dudley


6
@JensG Itu sebabnya Anda memasukkannya ke dalam pesan commit, dan logpada file tersebut akan memberikan Anda hal yang persis sama, tetapi tanpa mengacaukan file ...
Izkata

1
@ JensG Dan kapan Anda telah memperbaiki skor atau ratusan cacat pada file tertentu? Jawaban yang jelas adalah bahwa Anda secara berkala menghapus ID basi, tetapi kemudian Anda kembali untuk mengambil log VC ...
dmckee

3
Pertanyaan ini adalah subjek artikel Ars Technica. Haruskah kita daftar bug di header file sumber? (diterbitkan 15 hari setelah pertanyaan ini diposting).
Peter Mortensen

Jawaban:


107

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.


2
"dan jika Anda menggunakan sistem kontrol versi modern yang mendukung perubahan-set, maka sebenarnya kehilangan informasi tentang perubahan." - bisakah Anda menjelaskannya?
Geek

10
@ Tolong saya tidak yakin harus menjelaskan apa. Jika Anda melihat file yang referensi nomor ID bug, Anda tidak melihat file lain berubah sebagai akibat dari cacat yang sama kecuali jika Anda mencari file. Itulah yang merupakan perubahan-set - kumpulan file diperiksa bersama-sama.
Thomas Owens

9
Saya juga akan menambahkan bahwa jika Anda pindah ke sistem pelacakan bug baru maka semua angka itu menjadi tidak berharga secara instan. Saya sudah menemukan itu di pekerjaan saya saat ini di mana beberapa komentar memiliki nomor dari perangkat lunak pelacakan bug yang belum digunakan dalam 10 tahun.
17 dari 26

2
Jadi setelah mengubah ke sistem pelacakan bug baru, mereka menjadi berguna seolah-olah mereka tidak pernah ada. Tetapi dengan asumsi mereka memberikan nilai pada titik tertentu, dan tidak memberikan nilai negatif sekarang, mengapa tidak melakukannya?
Cruncher

@ 17of26 - Saya membayangkan Anda dapat menautkan bug / masalah lama ke yang baru, jika tidak melalui mekanisme selain sebagai komentar seperti "bug pelacak isu lama 1234".
Kenny Evitt

42

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.


19
Mungkin saya agak sombong, tetapi jika foo()tidak boleh dipanggil secara langsung, maka kode harus disusun sedemikian rupa sehingga tidak bisa.
MetaFight

20
Oh, saya mencoba menulis sesuatu sebagai contoh, untuk membuat teks lebih konkret - jangan menganggap saya terlalu harfiah. Kasus yang lebih baik adalah kasus di mana Anda menggunakan pustaka eksternal, dan fungsi yang biasanya Anda gunakan untuk tujuan tertentu memiliki bug. Maka komentar "Jangan panggil di foo()sini" akan masuk akal.
rem

16

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.


Menurut Anda, berapa banyak bug yang mungkin dilakukan dalam satu file dan jika ada banyak, mungkin inilah saatnya untuk menulis ulang.
Andy

11

Tidak.

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


2
yang merupakan semacam sistem kontrol versi (dan yang saya lihat digunakan secara operasional di rumah-rumah peranti lunak sesingkat tahun 2006, dan tidak diragukan lagi sedang digunakan di suatu tempat saat ini).
jwenting

1
@jwenting Saya telah melihat pertanyaan di situs ini dari orang-orang yang cukup malang untuk saat ini bekerja di toko-toko di mana itu adalah praktik saat ini :-(
Carson63000

Kami menggunakan sistem kontrol sumber yang bagus. Tidak seorang pun kecuali saya yang memberikan komentar ketika memeriksa kode. <shrug> Saya mengomentari hal-hal tertentu (seperti PLSQL yang tidak selalu dilacak oleh SCM). Saya mengomentari kode saya untuk menjelaskan, tetapi tidak pernah mengikatnya kembali ke bug tertentu, tetapi saya selalu merujuk bug di SCM memberikan komentar ketika saya check in. Semoga nantinya seseorang akan menghargainya.
Pedantic

11

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).


8

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.


3
Benar. Kadang-kadang saya memiliki sedikit perasaan, bahwa programmer merasa takut dengan redundansi, sehingga mereka menghindari informasi yang sama diakses melalui cara yang berbeda. Itu sangat menarik, karena programmer biasanya juga ngeri dengan kinerja buruk dan karenanya menggunakan cache dalam program mereka. Tetapi caching nomor bug dalam kode di sebelah tempat yang paling berguna dianggap buruk? Mmmh
JensG

Seringkali ada cara lain untuk mendapatkan informasi itu (pada proyek yang sedang saya kerjakan, itu adalah right click > Team > Show Annotationsuntuk mendapatkan kesalahan git dari file saat ini), tetapi perbedaannya adalah, dengan komentar ada dapat ditemukan - mereka dapat melompat keluar pada Anda - dan dengan anotasi, Anda harus secara sadar memutuskan untuk mencari mereka.
David Conrad

Pikirkan, putuskan, klik, klik, klik, gulir. Itu sebabnya saya mengatakan "caching dalam kode". Jika ada di sana, saya hanya melihatnya.
JensG

2
@JensG sudut pandang yang menarik. Cache dapat meningkatkan kinerja tetapi mereka juga memiliki biaya penyimpanan. Jika cache harus diisi, diperbarui, tidak valid, disiram, dan sebagainya dengan upaya manusia yang berlebihan, saya akan mempertanyakan rasio biaya-manfaat, terutama mengingat betapa mengerikannya manusia dalam menjaga konstruksi yang didenormalisasi sedemikian sinkron.
Jeffrey Hantin

7

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.


1
Lihat contoh dalam pertanyaan - komentar akan merujuk pada basis data bug ...
Izkata

@Izkata Tapi itu intinya. Basis data itu sendiri mungkin memiliki bidang "komentar" dengan komentar. Pertanyaannya bukan tentang memiliki database bug atau tidak, tetapi tentang apakah menyimpannya di file sumber adalah ide yang bagus. Saya pikir, bahkan jika itu adalah komentar, mereka harus disimpan dalam database itu sendiri karena memang untuk itulah.
Pierre Arlaud

6

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.


2

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 :)


2

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.


2

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.


2

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 .


Pemberitahuan hak cipta juga ada di sana untuk (sedikit berlebihan) memberi tahu karyawan bahwa file tersebut milik majikan. Dan mungkin enggan berbagi ilegal (bahkan oleh karyawan), dilihat berapa banyak orang tampaknya berpikir bahwa hak cipta hanya berlaku jika ada adalah pemberitahuan.
Bernd Jendrissek

1

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.


3
pertanyaan adalah tentang komentar di awal file sumber, tepat setelah pesan hak cipta - ini tidak ada hubungannya dengan komentar di ruang lingkup yang lebih sempit
agas

Semua jawaban di sini berbicara tentang hal itu. Jika saya membuat perubahan signifikan pada seluruh file kelas (reorg atau memperbaiki format), apakah saya tidak akan berkomentar file kelas sebagai ruang lingkup?
StingyJack

0

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.


0

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.


ini tampaknya tidak menambah nilai substansial pada apa yang sudah diposting di jawaban sebelumnya
nyamuk

0

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.

Dengan menggunakan situs kami, Anda mengakui telah membaca dan memahami Kebijakan Cookie dan Kebijakan Privasi kami.
Licensed under cc by-sa 3.0 with attribution required.