Apakah ada titik untuk memasukkan "log perubahan" di setiap file kode ketika Anda menggunakan kontrol versi?

Saya mendapat kesan bahwa sistem kontrol versi menghilangkan kebutuhan untuk memiliki "log perubahan" terpampang di mana-mana dalam kode. Saya sering melihat terus menggunakan log perubahan, termasuk blok panjang yang besar pada awal prosedur tersimpan dengan bagian besar diblokir untuk perubahan pada file dan mengotori kode dengan hal-hal seperti:

// 2011-06-14 (John Smith) Change XYZ to ABC to fix Bug #999

dan:

// 2009-95-12 (Bob Jones) Extracted this code to Class Foo 
// <commented-out code here>

Alasan untuk ini, seperti yang dijelaskan kepada saya, adalah bahwa terlalu lama untuk menyaring log VCS kami mencoba untuk menemukan siapa yang mengubah apa dan mengapa, sambil menyimpannya dalam file kode itu sendiri, baik di bagian atas atau dekat yang relevan berubah, membuatnya mudah untuk melihat siapa yang mengubah apa dan kapan. Sementara saya melihat intinya, sepertinya berlebihan dan hanya semacam menampar "Eh kita tidak benar-benar mengerti bagaimana menggunakan VCS kita dengan benar, jadi kita tidak akan repot-repot dengan hal itu sama sekali."

Bagaimana menurut anda? Apakah Anda menggunakan komentar dan log? Hanya log? Apakah Anda menemukan bahwa lebih mudah untuk membuat kode ketika Anda dapat melihat di atas blok kode bahwa John Smith mengubah metode untuk memeriksa XYZ seminggu yang lalu, daripada harus mencari melalui log dan membandingkan file kode dalam alat Diff?

EDIT: Menggunakan SVN, tetapi pada dasarnya hanya sebagai repositori. Tidak ada cabang, tidak ada gabungan, tidak ada apa pun kecuali penyimpanan log +.

Saya cenderung menghapus komentar dalam kode. Dan dengan menghapus, maksud saya, dengan prasangka . Kecuali komentar menjelaskan mengapa fungsi tertentu melakukan sesuatu, itu hilang. Sampai jumpa. Jangan lulus pergi.

Jadi seharusnya tidak mengejutkan Anda bahwa saya juga akan menghapus changelogs itu, untuk alasan yang sama.

Masalah dengan mengomentari kode dan komentar yang bertuliskan seperti buku adalah Anda tidak benar-benar tahu seberapa relevannya dan memberi Anda pemahaman yang salah tentang apa yang sebenarnya dilakukan oleh kode tersebut.

Sepertinya tim Anda tidak memiliki peralatan yang baik di sekitar sistem kontrol Versi Anda. Karena Anda mengatakan Anda menggunakan Subversion, saya ingin menunjukkan bahwa ada banyak tooling yang akan membantu Anda mengelola repositori subversi Anda. Dari kemampuan untuk menavigasi sumber Anda melalui web, hingga menautkan perubahan Anda ke bug tertentu, Anda dapat melakukan banyak hal yang mengurangi kebutuhan akan 'changelogs' ini.

Saya punya banyak orang berkomentar dan mengatakan bahwa mungkin saya keliru karena menghapus komentar. Sebagian besar kode yang pernah saya lihat yang telah dikomentari adalah kode yang buruk, dan komentar-komentar itu hanya mengacaukan masalahnya. Bahkan, jika saya pernah berkomentar kode, Anda dapat yakin bahwa saya meminta pengampunan dari programmer maintanence karena saya relatif yakin mereka akan ingin membunuh saya.

Tapi jangan sampai Anda pikir saya mengatakan bahwa komentar harus dihapus bercanda, pengiriman WTF harian ini (dari basis kode yang saya kerjakan) menggambarkan poin saya dengan sempurna:

/// The GaidenCommand is a specialized Command for use by the
/// CommandManager.
///
/// Note, the word "gaiden" is Japanese and means "side story",
/// see "http://en.wikipedia.org/wiki/Gaiden".
/// Why did I call this "GaidenCommand"? Because it's very similar to
/// a regular Command, but it serves the CommandManager in a different
/// way, and it is not the same as a regular "Command". Also
/// "CommandManagerCommand" is far too long to write. I also toyed with
/// calling this the "AlephCommand", Aleph being a silent Hebrew
/// letter, but Gaiden sounded better.

Oh ... Kisah-kisah yang bisa saya ceritakan tentang basis kode itu, dan saya akan, kecuali bahwa itu masih digunakan oleh salah satu organisasi pemerintah terbesar di sekitar.

"Change-log" yang disematkan dalam kode tersebut khususnya adalah naff. Mereka hanya muncul sebagai perbedaan lain ketika Anda berbeda revisi, dan satu yang tidak Anda pedulikan. Percayai VCS Anda - sebagian besar memiliki fitur "menyalahkan" yang akan menunjukkan kepada Anda dengan sangat cepat siapa yang mengubah apa.

Tentu saja hal yang sangat mengerikan adalah fitur VCS "lama" di mana Anda dapat memiliki log VCS yang sebenarnya tertanam dalam file sumber. Membuat penggabungan hampir mustahil.

Saya memiliki satu file ChangeLog untuk setiap proyek yang secara otomatis diisi oleh pesan komit tertentu.

Kami tidak menyertakan komentar ChangeLog. Jika kami melakukannya, saya akan menghapusnya dan "berbicara" dengan orang yang menambahkannya. Saya pikir mereka menunjukkan tidak memahami alat yang Anda gunakan, khususnya vcs.

Kami memiliki format untuk mengkomit pesan yang membuatnya lebih mudah untuk menangkap log. Kami juga melarang pesan yang tidak berguna atau ambigu.

Saya pribadi benci log perubahan dalam file kode sumber. Bagi saya, ini terasa seperti melanggar prinsip rekayasa perangkat lunak karena setiap perubahan yang saya buat harus dilakukan di banyak tempat. Seringkali informasi perubahan log sama sekali tidak berguna dan tidak penting. Menurut pendapat saya, perubahan pada perangkat lunak harus didokumentasikan ketika Anda memeriksa kode.

Tapi apa yang saya tahu ...

Saya berpikir bahwa jika ada desakan pada penerapan praktik menjaga log perubahan dalam kode sumber bahwa log perubahan harus dibatasi pada perubahan yang mempengaruhi API / antarmuka pulic kelas. Jika Anda membuat perubahan di dalam kelas yang tidak akan memecah kode apa pun yang menggunakannya, merekam perubahan ini dalam log perubahan hanya berantakan menurut pendapat saya. Namun, saya dapat melihat bagaimana kadang-kadang berguna untuk dapat memeriksa bagian atas file kode sumber untuk dokumentasi tentang setiap perubahan yang mungkin telah merusak apa pun untuk orang lain. Hanya ringkasan tentang bagaimana perubahan itu dapat memengaruhi API dan mengapa perubahan itu dilakukan.

Di sisi lain, toko saya terutama melakukan hal-hal C #, dan kami selalu menggunakan komentar inline XML untuk mendokumentasikan API kami, jadi membaca dokumentasi tentang perubahan API publik kurang lebih sesederhana menggunakan intellisense.

Saya berpikir bahwa bersikeras log perubahan dalam file sumber hanya menambahkan gesekan yang tidak perlu ke mesin dan mengalahkan salah satu tujuan menerapkan sistem kontrol versi di tempat pertama.

Perusahaan terakhir tempat saya bekerja memiliki perangkat lunak yang memiliki 17 tahun sejarah, pengembangan, dan pembaruan tahunan di belakangnya. Tidak semua migrasi dari satu sistem kontrol versi ke versi berikutnya akan menyimpan komentar atau catatan masuk. Semua pengembang selama bertahun-tahun juga tidak mempertahankan konsistensi dengan komentar / catatan check-in.

Dengan komentar dalam kode sumber, sejarah arkeologis perubahan disimpan sebagai catatan, bukan kode komentar. Dan, ya, mereka masih mengirimkan kode VB6.

Kontrol versi dapat menggantikan komentar log perubahan itu dalam kode jika devs di tim Anda menggunakannya dengan benar.

Jika tim Anda tidak menambahkan komentar saat check-in, atau meninggalkan komentar yang tidak membantu, maka akan sangat sulit untuk menemukan informasi yang Anda cari di masa mendatang.

Di perusahaan saya saat ini, kami diharuskan untuk mengirimkan komentar pada setiap check-in. Tidak hanya itu, tetapi kami diharapkan untuk melampirkan setiap check-in dengan tiket di Jira. Ketika Anda melihat Jira di masa depan, Anda dapat melihat setiap file yang telah diperiksa dan kapan untuk masalah itu bersama dengan komentar yang tersisa. Ini sangat berguna.

Pada dasarnya, kontrol versi hanya alat, itu adalah cara tim Anda menggunakan alat itu yang akan memberikan keuntungan yang Anda cari. Semua orang di tim harus setuju dengan bagaimana mereka akan menggunakannya untuk menyediakan pelacakan perbaikan bug sebaik revisi kode bersih.

Ini adalah sisa dari hari-hari ketika log VCS membingungkan dan sistem VCS sulit untuk ditangani (saya ingat hari-hari itu, di suatu tempat di backend tahun 80-an).

Kecurigaan Anda sepenuhnya benar, komentar-komentar ini lebih merupakan penghalang daripada bantuan dan setiap VCS modern akan memungkinkan Anda untuk menemukan apa yang Anda cari. Tentu saja, Anda (dan kolega Anda) harus mengeluarkan biaya sekitar. 30-60 menit mempelajari cara menggerakkan semua fitur ini (yang saya curigai, sebenarnya adalah alasan mengapa komentar ini masih ada).

Saya menyimpannya (hampir) bersama George. Komentar dalam kode hanya benar-benar dibenarkan jika mereka menjelaskan sesuatu yang tidak segera terlihat dalam kode itu sendiri. Dan itu jarang terjadi dalam kode yang baik. Jika Anda perlu memiliki banyak komentar dalam kode Anda, itu bau sendiri dan berteriak "refactor me!".

Kami masih memasukkannya dalam sumber prosedur tersimpan karena itulah cara kami dapat mengetahui versi mana yang ada di klien. Sisa aplikasi didistribusikan dikompilasi, jadi kami memiliki nomor versi modul yang menghubungkan kembali ke sumber, tetapi SP didistribusikan sebagai sumber ke klien untuk kompilasi dalam database lokal.

Kode PowerBuilder lawas kami masih menggunakannya, tapi saya pikir itu hanya sebagai faktor kenyamanan bagi peeps tertentu. Itu juga dikompilasi untuk distribusi, jadi (IMO mereka seharusnya) menggunakan sejarah VCS sialan.

Jika Anda menggunakan SVN, melakukan itu adalah buang-buang waktu dan sama sekali tidak berguna.

SVN memiliki fungsi menyalahkan. Itu akan memberi tahu Anda dengan tepat siapa yang membuat setiap baris dalam file yang diberikan, dan kapan.

Mengganti komentar log sangat membantu dalam kode ketika mereka membantu pengembang berikutnya mengajukan pertanyaan yang lebih baik tentang persyaratan baru. Ketika seorang pengembang melihat komentar, misalnya, bahwa Fred membuat bidang Foo diperlukan 6 bulan yang lalu untuk memenuhi beberapa persyaratan, pengembang tahu bahwa mereka perlu mengajukan beberapa pertanyaan sebelum mengimplementasikan permintaan terbaru untuk menjadikan Foo opsional. Ketika Anda berurusan dengan sistem yang kompleks, pemangku kepentingan yang berbeda cenderung memiliki prioritas dan keinginan yang berbeda. Mengganti komentar log dapat sangat membantu untuk mendokumentasikan trade-off mana yang telah dibuat untuk menghindari masalah di masa depan.

Sekarang, jika setiap pengembang memeriksa riwayat lengkap dari setiap baris kode sebelum membuat perubahan, komentar di dalam kode ini akan menjadi berlebihan. Tapi ini sangat tidak realistis baik dari sudut pandang alur kerja - sebagian besar pengembang hanya akan mengubah validasi tanpa meneliti sejarah tentang siapa yang menambahkannya dan mengapa - dan dari sudut pandang teknologi - sistem kontrol versi akan mengalami kesulitan melacak "sama" "baris kode jika telah berpindah dari satu baris ke yang lain atau telah direaktor ulang ke kelas yang berbeda. Komentar dalam kode jauh lebih mungkin untuk dilihat dan, yang lebih penting, untuk mendorong pengembang berikutnya untuk memperhatikan bahwa perubahan yang tampaknya sederhana mungkin tidak begitu sederhana.

Yang sedang berkata, komentar perubahan log dalam kode harus relatif jarang. Saya tidak menganjurkan agar komentar log perubahan ditambahkan setiap kali sedikit kode dire-refored atau ketika bug benar diperbaiki. Tetapi jika persyaratan asli adalah "Foo adalah opsional" dan seseorang datang dan mengubah persyaratan untuk "Foo diperlukan untuk mendukung proses hilir Bar" itu adalah sesuatu yang saya akan sangat mempertimbangkan menambahkan komentar untuk. Karena ada kemungkinan kuat bahwa beberapa pengguna / analis masa depan akan tidak mengetahui proses downstream Bar dan tidak mengetahui alasan mengapa Foo diperlukan dan akan meminta untuk membuat Foo opsional lagi dan menyebabkan sakit kepala dalam proses Bar.

Dan ini sebelum mempertimbangkan bahwa organisasi dapat memutuskan untuk mengubah sistem kontrol versi mereka dengan beberapa frekuensi terutama ketika mereka tumbuh dari perusahaan kecil dengan beberapa pengembang menjadi perusahaan yang jauh lebih besar. Migrasi ini akan sering mengakibatkan hilangnya komentar perubahan log - hanya komentar dalam kode yang akan dipertahankan.

Saya terkejut melihat tidak ada yang menyebutkan ini, tetapi bukankah alasan asli untuk ini mematuhi persyaratan lisensi? Artinya, beberapa lisensi mengatakan bahwa setiap perubahan yang Anda buat pada file harus dicatat dalam file itu sendiri?

Alasan mengapa kami terus memelihara log perubahan di bagian komentar kami adalah untuk kemudahan penggunaan. Seringkali ketika men-debug masalah lebih mudah untuk menggulir ke bagian atas file dan membaca log perubahan daripada membuka file kontrol sumber, menemukan file di dalamnya, dan menemukan perubahan yang dibuat