Sürüm kontrolünü kullanırken her kod dosyasına bir "değişiklik günlüğü" eklemenin bir anlamı var mı?

Sürüm kontrol sisteminin, kodun her yerine "günlük değiştir" ihtiyacını ortadan kaldırdığı izlenimini edindim. Sık sık kayıt kütüklerinin kullanılmaya devam ettiğini gördüm, saklı yordamların başlangıcındaki büyük uzun bloklar da dahil olmak üzere dosyada yapılan değişiklikler nedeniyle engellenen büyük bir blok ve kodun aşağıdaki gibi şeylerle çevrilmesi:

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

ve:

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

Bunun nedeni, bana açıklandığı gibi, en üstte veya ilgili kod dosyasındayken kod dosyasındayken neyi ve neyi değiştirdiğini bulmaya çalışan VCS kayıtlarımızda elemenin çok uzun sürmesidir. değiştir, kimin neyi ne zaman değiştirdiğini görmeyi kolaylaştırır. Bunun ne olduğunu görmeme rağmen, artık gereksiz ve sadece "VCS'imizi nasıl doğru kullanacağımızı gerçekten bilmiyoruz, bu yüzden bu şeylerle uğraşmayacağız."

Ne düşünüyorsun? Hem yorumları hem de günlüğü kullanıyor musunuz? Sadece kütük? Günlükleri araştırmak ve bir Diff aracındaki kod dosyalarını karşılaştırmak yerine, John Smith'in bir hafta önce XYZ'i denetleme yöntemini değiştirdiği bir kod bloğunun yukarısında gördüğünüzde kodlamanın daha kolay olduğunu düşünüyor musunuz?

EDIT: SVN kullanmak, fakat temelde sadece bir depo olarak. Dal yok, birleşme yok, log + depolama dışında hiçbir şey yok.

Koddaki yorumları silme eğilimindeyim. Ve silerek, önyargılı demek istiyorum . Bir yorum, belirli bir işlevin neden bir şeyi yaptığını açıklamazsa , ortadan kaybolur. Güle güle. Geçme gitme.

Bu yüzden, aynı sebeple bu değişmezleri de silmem sizi şaşırtmamalı.

Yorumlanan kod ve kitap gibi okunan yorumlardaki sorun, bunun gerçekten ne kadar alakalı olduğunu bilmemeniz ve size kodun gerçekte ne yaptığına dair yanlış bir anlama hissi vermenizdir.

Takımınızın Sürüm kontrol sisteminizde başarılı bir takım yok gibi görünüyor. Subversion kullandığınızı söylediğinizden beri, subversion deponuzu yönetmenize yardımcı olacak birçok araç olduğunu belirtmek isterim. Kaynağınızı web'de dolaşma yeteneğinden, değişiklik kümelerinizi belirli hatalara bağlamaya kadar, bu 'değişmezler' ihtiyacını azaltan çok şey yapabilirsiniz.

Bir sürü insan yorum yaptı ve belki de yorumları silmek için hatalı olduğumu söyledim. Yorum yaptığım kodun büyük çoğunluğu hatalı koddu ve yorumlar yalnızca sorunu engelledi. Aslında, herhangi bir kod hakkında yorum yaparsam, bakım programcısından affedilmeyi istediğimden emin olabilirsiniz çünkü beni öldürmek isteyeceklerinden oldukça eminim.

Ancak, yorumlarınızın jestlerle silinmesi gerektiğini söylesem, bu Günlük WTF gönderimi (üzerinde çalıştığım bir kod tabanından) amacımı mükemmel bir şekilde gösteriyor:

/// 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 ... Size o kod temeli hakkında anlatabileceğim hikayeler ve ben hala etraftaki en büyük devlet kurumlarından biri tarafından kullanılıyor olması dışında, yaparım.

Bu koda gömülü olan "değişiklik günlükleri" özellikle çok açık. Sadece revizyonları değiştirdiğinizde ve gerçekten umursamadığınız biri olduğunda başka bir fark olarak ortaya çıkıyorlar. VCS'nize güvenin - çoğunda neyin değiştiğini size çok çabuk gösterecek bir "suçlama" özelliği var.

Tabii ki gerçekten korkunç olan şey, eski VCS'lerin kaynak dosyalara gömülü gerçek VCS günlüğüne sahip olabileceği özelliğiydi. Birleştirme neredeyse imkansız hale getirildi.

Belirli taahhüt mesajları tarafından otomatik olarak doldurulan her proje için tek bir ChangeLog dosyasına sahibim.

ChangeLog yorumlarınızı gömmedik. Yapsaydık, onları çıkarır ve ekleyen kişiyle bir "konuşur" olurdum. Sanırım kullandığınız araçları, özellikle de vcs'yi anlamadıklarını gösteriyor.

Kayıtları tutmayı kolaylaştıran kayıt mesajları için bir formatımız var. Ayrıca işe yaramaz ya da belirsiz taahhüt mesajlarına da izin vermeyiz.

Şahsen kod kaynak dosyasındaki değişiklik kayıtlarından nefret ediyorum. Bana göre sadece, yaptığım herhangi bir değişikliğin birden fazla yerde yapılması gereken bir yazılım mühendisliği ilkesini ihlal ediyormuş gibi geliyor. Değişiklik günlüğü bilgileri çoğu zaman tamamen işe yaramaz ve önemsizdir. Benim düşünceme göre, koddakileri kontrol ettiğinizde yazılım değişiklikleri belgelenmelidir.

Ama ben ne biliyorum ki ...

Kaynak kodun içinde bir değişiklik günlüğü tutma uygulamasının uygulanması konusunda bir ısrar varsa, değişiklik günlüğünün sınıfın API / arayüzünü etkileyen değişikliklerle sınırlı olması gerektiğini düşünüyorum. Sınıf içinde, onu kullanan herhangi bir kodu kırmayacak değişiklikler yapıyorsanız, bu değişiklikleri bir değişiklik günlüğüne kaydetmek bence sadece karışıklık yaratır. Ancak, başkaları için herhangi bir şeyi bozabilecek herhangi bir değişiklikle ilgili belgeler için kaynak kod dosyasının en üstünü kontrol etmenin bazen kullanışlı olabileceğini görebiliyorum. Değişikliğin API'yi nasıl etkileyebileceği ve değişikliğin neden yapıldığı hakkında bir özet.

Öte yandan, dükkanım öncelikle C # işleri yapıyor ve API'mızı belgelemek için her zaman satır içi XML yorumları kullanıyoruz, bu nedenle genel API değişiklikleriyle ilgili belgeleri okumak, intellisense'i kullanmak kadar basit.

Kaynak dosyadaki bir değişiklik günlüğünde ısrar etmenin, makineye gereksiz sürtünme eklemek olduğunu ve ilk olarak sürüm kontrol sisteminin uygulanmasının amaçlarından birini yendiğini düşünüyorum.

Çalıştığım en son şirket, 17 yıllık geçmişe, geliştirmeye ve yıllık güncellemelere sahip bir yazılıma sahipti. Bir sürüm kontrol sisteminden diğerine tüm geçişler yorumları veya giriş notlarını korumaz. Bu yıllar içindeki tüm geliştiriciler, check-in yorumları / notlarıyla herhangi bir tutarlılık sağlamamıştır.

Kaynak koddaki yorumlarla, değişikliklerin arkeolojik geçmişi kod dışına alınmadan not olarak tutuldu. Ve evet, hala VB6 kodunu gönderiyorlar.

Sürüm kontrolü, ekibinizdeki aygıtlar doğru kullanıyorsa, koddaki bu değişiklik günlüğü yorumlarını değiştirebilir.

Ekibiniz check-in sırasında yorum eklemiyorsa veya yararsız yorumlar bırakmıyorsa, gelecekte aradığınız bilgileri bulmak oldukça zor olacaktır.

Mevcut şirketimde, her check-in sırasında yorum göndermemiz gerekiyor. Sadece bu da değil, her check-in'i Jira'da bir biletle eklememiz bekleniyor. Gelecekte Jira'ya baktığınızda, teslim edilmiş her dosyayı ve o konuda ne zaman kalan yorum ile birlikte görebilirsiniz. Oldukça kullanışlı.

Temel olarak, sürüm kontrolü sadece bir araçtır, ekibinizin aradığınız avantajları sağlayacak o aracı nasıl kullandığıdır. Ekipteki herkesin hata düzeltme takibi ve temiz kod revizyonları sağlamak için onu en iyi nasıl kullanacaklarına karar vermeleri gerekiyor.

Bu, VCS kütüklerinin kafa karıştırıcı olduğu ve VCS sistemlerinin ele alınmasının zor olduğu günlerin artıklarıdır (80'lerin arkasındaki bir yerde o günleri hatırlıyorum).

Sizin şüphe tamamen doğru olduğunu, bu yorumlar bir yardım daha bir engel daha fazla olan ve herhangi bir modern VCS Aradığınız tam olarak ne bulmak için izin verecektir. Tabii ki, siz ve meslektaşlarınız yaklaşık olarak harcamak zorunda kalacaksınız. (Bu yorumlar hala orada olmasının nedeni aslında hangi sanıyorum,) tüm bu özellikleri araba kullanmayı öğreniyor 30-60 dakika.

George'la (neredeyse) saklıyorum. Koddaki yorumlar, yalnızca kodun içinde hemen görünmeyen bir şeyi açıklarlarsa gerçekten haklı çıkar. Ve bu sadece nadiren iyi kodda olur. Eğer kodunuzda bolca yorum yapmanız gerekiyorsa, bu kendisinin kokusu ve "beni yeniden düşün!" Diye bağırıyor.

Bunları hala saklı yordam kaynağına dahil ediyoruz, çünkü müşteride tam olarak hangi sürümün mevcut olduğunu söyleyebiliriz. Uygulamanın geri kalanı derlenmiş olarak dağıtılır, bu nedenle kaynağa geri bağlanan modül sürüm numaralarımız vardır, ancak SP'ler yerel veritabanında derleme için istemcilere kaynak olarak dağıtılmaktadır.

Eski PowerBuilder kodumuz hala bunları kullanıyor, ancak bence bu sadece bazı gözetmenler için rahatlık faktörü. Bu aynı zamanda dağıtım için derlenir, yani (IMO'lar gerekir) friggin VCS geçmişini kullanır.

SVN kullanıyorsanız, bunu yapmak zaman kaybı ve tamamen işe yaramaz.

SVN'nin suçlama işlevi vardır. Bu size tam olarak belirli bir dosyadaki her satırı kimin ve ne zaman yaptığını söyleyecektir.

Değişiklik günlüğü yorumları, müteakip bir geliştiricinin yeni gereksinimlerle ilgili daha iyi sorular sormasına yardımcı olduklarında kodda son derece faydalıdır. Bir geliştirici, örneğin, Fred'in, bir gereksinimi karşılamak için 6 ay önce Foo alanını gerekli kıldığı yönünde bir yorum gördüğünde, bu geliştirici, Foo'yu isteğe bağlı yapmak için en son isteği uygulamadan önce bazı soru sormaları gerektiğini bilir. Karmaşık sistemlerle uğraşırken farklı paydaşların farklı önceliklere ve farklı arzulara sahip olmaları muhtemeldir. Değişiklik kayıt defteri yorumları, gelecekteki sorunlardan kaçınmak için bu takasların hangilerinin yapıldığını belgelemek için çok yararlı olabilir.

Şimdi, her geliştirici, herhangi bir değişiklik yapmadan önce her kod satırının geçmişini kontrol etmişse, bu yorumların kodda olması gereksiz olacaktır. Ancak bu, hem iş akışı açısından çok gerçekçi değil - çoğu geliştirici, onaylayanın tarihini, nedenini ve nedenini aramaya gerek kalmadan doğrulamayı değiştirir - ve bir teknoloji açısından - bir sürüm kontrol sistemi, "aynısını izlemekte zorlanırdı "eğer bir satırdan diğerine taşınmışsa veya farklı bir sınıfa yeniden yerleştirilmişse, kod satırı. Koddaki yorumların görülmesi daha olasıdır ve daha da önemlisi müteakip bir geliştiriciden görünüşte basit bir değişikliğin bu kadar basit olamayacağına dikkat etmesini isteme.

Olduğu söyleniyor, kodunda değişiklik günlüğü yorumları nispeten nadir olmalıdır. Bir değişiklik kodu her yeniden yapılandırıldığında veya gerçek bir hata giderildiğinde değişiklik günlüğü yorumlarının eklenmesini savunmuyorum. Ancak, asıl gereksinim "Foo isteğe bağlıdır" ise ve birileri ortaya çıkıp, "aşağı yönde işlem Çubuğunu desteklemek için Foo gereklidir" koşulunu değiştirirse, bu yorum için şunu eklemeyi şiddetle isterim. Çünkü gelecekteki bazı kullanıcı / analistlerin akış aşağı Bar işleminden habersiz olmaları ve Foo'nun gerekli olmasının nedenlerinden habersiz olmaları ve Foo'yu tekrar isteğe bağlı hale getirmelerini ve Bar işleminde baş ağrılarına neden olmalarını isteyecekleri güçlü bir ihtimaldir.

Bu da, kuruluşların sürüm kontrol sistemlerini, özellikle az sayıda geliştiriciden küçük şirketlerden daha büyük şirketlere doğru büyüdükçe, bazı sıklıkta değiştirmeye karar verebileceklerini düşünmeden önce. Bu göçler genellikle değişiklik günlüğü yorumlarının kaybına neden olur - yalnızca koddaki yorumlar korunur.

Bundan kimsenin bahsetmediğini görünce şaşırdım, ancak bunun lisans gerekliliklerine uymasının asıl nedeni değil mi? Yani, bazı lisanslar dosyada yaptığınız herhangi bir değişikliğin dosyanın kendisinde belirtilmesi gerektiğini söylüyor.

Yorumlar bölümünde bir değişiklik günlüğü tutmaya devam etmemizin nedeni kullanım kolaylığı içindir. Genellikle bir hata ayıklama sırasında dosyanın üstüne kaydırmak ve değişiklik günlüğünü okumak, kaynak kontrol dosyasını açmaktan, içindeki dosyayı bulmaktan ve yapılan değişiklikleri bulmaktan daha kolaydır.