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

75

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

version-control coding-standards maintenance

— Wayne Molina
sumber

4

Sistem kontrol versi mana yang Anda gunakan?

— ChrisF

11

Beberapa toko menggunakan log perubahan sebelum ada sistem kontrol sumber. Kelembaman dan keakraban membuat perubahan log sekitar.

— Gilbert Le Blanc

2

+1 - Tim saya juga melakukan ini, dan saya mencoba meyakinkan beberapa dari mereka bahwa itu adalah peran VCS. Masalahnya dimulai ketika komentar ini tidak diperbarui dengan kode aktual ... Dan yang terburuk adalah manajemen memutuskan untuk menambahkan changelogs ke setiap metode juga.

— slaphappy

2

+1 - Saya telah bertarung dengan pengembang senior kami selama hampir dua tahun tentang ini. Satu-satunya alasan untuk menambahkan komentar yang tidak berguna ini adalah membuat penggabungan perubahan pada metode 3000-line menjadi lebih mudah. Gagasan bahwa metode 3000-line adalah cabul bertemu dengan cemoohan.

— Joshua Smith

1

Jika "butuh terlalu lama untuk menyaring log VCS [Anda]", Anda melakukan sesuatu yang salah.

— Keith Thompson

46

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.

— George Stocker
sumber

4

Setiap kali saya berjuang dengan bagian tertentu dari logika yang kompleks, komentar kadang-kadang dapat membantu saya mendapatkan beberapa konteks mengapa logika itu berbelit-belit. Tapi secara keseluruhan saya setuju dengan Anda.

— maple_shaft

5

Setiap pengembang memiliki setidaknya beberapa kualitas buruk, saya tahu saya tidak boleh tetapi saya tidak bisa berhenti :) Setiap kali saya membuat TODOkomentar anak anjing mati.

— maple_shaft

32

Menghapus komentar orang lain dengan prasangka adalah dengan cara memaksa gaya pemrograman Anda sendiri dan kepercayaan pada orang lain. Pemrogram junior dan pasifis tidak akan menyalak kembali, tetapi sesekali Anda bertemu dengan alpha alpha, dan kemudian perkelahian yang seharusnya tidak dimulai. Jadi, Anda telah membaca di blog pintar orang pintar bahwa ketika sampai pada komentar, lebih sedikit lebih banyak. Orang lain mungkin tidak membaca buku yang sama. Bahkan jika Anda berpikir Anda benar karena beberapa orang di SO dengan 5k + perwakilan setuju, kediktatoran bukanlah cara untuk melakukan kerja kolaboratif. Saya bekerja di bawah laki-laki alfa sebelumnya dan berhenti.

— Pekerjaan

8

@Neil Butterworth: re: ructions: Kode dimaksudkan untuk ditempa. Refactor, ubah, perbaiki. Itu dimaksudkan untuk itu. Itu tidak dimaksudkan untuk ditulis sekali saja. Pemahaman kami tentang bisnis berubah dan ketika itu terjadi, kami perlu mengubah kode. Saya memiliki banyak masalah dengan komentar, tetapi yang paling relevan dengan diskusi kami adalah bahwa komentar jarang tetap sinkron dengan kode, dan umumnya mereka tidak menjelaskan mengapa sesuatu terjadi. Ketika itu terjadi, mudah untuk menghapusnya. Jika seseorang datang kepada saya dan bertanya mengapa saya menghapus komentar berikut file.Open() // Open the file. Saya akan tertawa.

— George Stocker

5

Beberapa hari yang lalu, saya menulis sepotong kode, perhitungan matematis yang sangat kompleks penuh dengan trigonometri, transformasi, apa pun ... Butuh sekitar setengah jam untuk menulis kurang dari 10 baris kode. Hampir tidak ada orang di sekitar saya yang mengerti cara kerjanya. Saya tidak akan memahaminya dalam beberapa minggu juga. Di sisi lain, mengapa itu ada yang sepele. Jadi, di atas beberapa baris itu, adalah seluruh bab teks, menjelaskan apa, bukan mengapa. Jika Anda datang dan menghapus komentar itu, saya akan meninju Anda di muka, sekrup dipecat.

— Davor Ždralo

76

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

— Neil Butterworth
sumber

14

Mereka tidak hanya muncul sebagai perbedaan lain, lebih buruk lagi, tetapi mereka juga bisa menjadi salah dari waktu ke waktu, sedangkan VCS yang baik akan selalu dapat memberi tahu Anda siapa yang benar-benar menulis baris tertentu, serta sejarah di sekitar baris itu. Satu-satunya hal yang lebih buruk daripada komentar tidak berguna adalah komentar berbahaya. Komentar-komentar ini dimulai sebagai tidak berguna dan akhirnya menjadi berbahaya, jika tidak sepenuhnya diabaikan.

— Ben Hocking

10

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.

— dietbuddha
sumber

8

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.

— John Connelly
sumber

6

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.

— Tangurena
sumber

5

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.

— Tyanna
sumber

5

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!".

— wolfgangsz
sumber

4

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.

— DaveE
sumber

1

+1 Saya akan menulis jawaban ini tetapi Anda telah menyelamatkan saya dari masalah. Tidak hanya prosedur tersimpan yang didistribusikan sebagai sumber, tetapi banyak bahasa scripting juga. Saya sering menggunakan OpenACS dan TCL - seringkali jika klien memiliki versi forked dari file tertentu, satu-satunya cara untuk DIJAMIN bahwa Anda tahu versi mana yang mereka miliki adalah dengan membaca log perubahan. Sangat berguna jika Anda masuk ke situs klien dan tidak dapat dengan mudah melakukan perbedaan dengan perangkat lunak kontrol versi.

— TrojanName

3

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.

— Apa namanya
sumber

1

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.

— Gua Justin
sumber

Apakah ada konversi VCS yang tidak menyimpan pesan komit?

— David Thornley

1

@ David - Saya sudah melihat banyak yang tidak. Saya tidak tahu apakah ada kendala teknis untuk melakukannya atau apakah seseorang memutuskan bahwa lebih mudah untuk hanya "memulai baru" dan memeriksa semua kode ke VCS baru pada hari 1.

— Justin Cave

menambahkan komentar yang menjelaskan mengapa suatu proses berubah bisa berguna, dan kadang-kadang menambahkan komentar yang menjelaskan ketika itu berubah, tapi saya tidak melihat ada baiknya menempatkan komentar itu dalam bentuk log perubahan. Untuk satu, itu agak menyamarkan kegunaan komentar ("Oh, itu hanya perubahan log komentar"), dan dua, itu mendorong lebih lanjut, komentar perubahan log yang tidak perlu (memperkuat # 1).

— Ben Hocking

Berhenti menggunakan sumber visual yang aman? Semua sistem kontrol sumber modern berguna menangani perubahan log dengan benar. Kami tahu ini secara definisi karena jika tidak, mereka tidak akan dianggap berguna. Luangkan 30 menit belajar menggunakan kontrol sumber yang Anda miliki, itu akan membuat Anda jauh lebih efektif daripada hanya berdoa seseorang yang tahu alat Anda akan memberi Anda beberapa remah. Belum lagi, cukup sering sejarah kode tidak relevan, Anda hanya menguji dan menulis sekarang, sekarang.

— ebyrob

Seperti untuk "mengubah kontrol sumber" - hampir semua sistem modern dapat memindahkan riwayat satu ke yang lain, menghasilkan file perubahan tingkat proyek individu, atau dengan sedikit usaha benar-benar menanamkan log perubahan mereka ke dalam file sumber (ketika itu menjadi sesuai pada suatu langkah tidak sebelum). Jadi teknologinya ada, orang memilih untuk tidak menggunakan kontrol sumber dengan benar adalah masalahnya.

— ebyrob

1

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?

— Sverre Rabbelier
sumber

1

lisensi mana yang mengatakan itu?

— Trasplazio Garzuglio

2

Saya bekerja di tempat di mana kepatuhan Sarbanes Oxley yang mereka yakini menuntut blok perubahan dalam file sumber. Mereka juga menggunakan PVC (alias "Dimensi") selama bertahun-tahun, jadi mereka benar-benar tidak memiliki kontrol versi apa pun, tetapi apa yang saya tahu?

— Bruce Ediger

@ Marsco: Saya tidak ingat atau saya akan menautkannya.

— Sverre Rabbelier

1

Bagian 2a dari GPLv2 membutuhkannya. Sebagian besar proyek mengabaikannya, beberapa memiliki file "ChangeLog" tunggal (sering dihasilkan dari VCS mereka).

— dsas

0

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

— pengantin
sumber

1

Secara pribadi, saya merasa agak sakit ketika file 200 baris menjadi 1.000 baris panjang karena menambahkan changelog ke setiap file sumber. Kebisingan ekstra ini sebenarnya mengaburkan apa yang penting sebelum lama sekali.

— ebyrob