Ben bir sürüm kontrol sistemi "değişiklik günlükleri" kod her yerde sıvalı olması ihtiyacını ortadan kaldı izlenimi altındaydı. Sık sık büyük bir bölüm saklı yordamlar başlangıcında büyük değişiklikler ile değişiklik günlükleri sürekli kullanım gördüm dosya değişiklikleri için bloke ve gibi şeyler ile kodu çöp:
// 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, VCS günlüklerimizi neyin değiştirdiğini ve neden değiştirdiğini bulmaya çalışırken, kod dosyasında, üstte veya ilgili değişim, kimin ne zaman ne değiştirdiğini görmeyi kolaylaştırır. Ben bu noktayı görürken, gereksiz görünüyor ve "Eh bizim VCS nasıl düzgün kullanılacağını gerçekten anlamıyoruz, bu yüzden bu şeylerle hiç uğraşmayacağız."
Ne düşünüyorsun? Hem yorumları hem de günlüğü kullanıyor musunuz? Sadece kütük mü? Bir kod bloğunun yukarısında, John Smith'in bir Diff aracında günlükleri aramak ve kod dosyalarını karşılaştırmak yerine, bir hafta önce XYZ'yi kontrol etme yöntemini değiştirdiğinde kodlamanın daha kolay olduğunu düşünüyor musunuz?
DÜZENLEME: SVN kullanımı, ancak temel olarak yalnızca depo olarak. Şube yok, birleştirme yok, günlük + depolama dışında hiçbir şey yok.
Koddaki yorumları silme eğilimindeyim. Ve silmekle, yani, önyargıyla . Bir yorum belirli bir işlevin neden bir şey yaptığını açıklamazsa, ortadan kalkar. Güle güle. Geçmeyin.
Bu nedenle, aynı sebepten dolayı bu değişiklik günlüklerini de silmem sizi şaşırtmamalı.
Yorumlanmış kod ve kitap gibi okunan yorumlarla ilgili sorun, gerçekten ne kadar alakalı olduğunu bilmemeniz ve kodun gerçekte ne yaptığına dair yanlış bir anlayış duygusu vermenizdir.
Ekibinizin Sürüm kontrol sisteminizde iyi bir takım bulunmadığı anlaşılıyor. Subversion kullandığınızı söylediğinizden, Subversion deponuzu yönetmenize yardımcı olacak birçok araç bulunduğunu belirtmek isterim. Kaynağınızda web'de gezinme yeteneğinden, değişiklik kümelerinizi belirli hatalara bağlamaya kadar, bu 'değişiklik günlükleri' ihtiyacını azaltan çok şey yapabilirsiniz.
Birçok kişi yorum yaptım ve belki de yorumları silmek için yanıldığımı söylüyorum. Yorumlandığını gördüğüm kodun büyük çoğunluğu kötü kod oldu ve yorumlar sadece sorunu gizledi. Aslında, kod yorum yaparsam, bakım programcısından af istediğimden emin olabilirsiniz çünkü beni öldürmek isteyeceklerinden eminim.
Ama yorumların jestle silinmesi gerektiğini söylesem bile, bu Günlük WTF gönderimi (üzerinde çalıştığım bir kod tabanından) benim 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 ... Sana bu kod tabanıyla ilgili anlatabileceğim hikayeler ve ben de, etraftaki en büyük hükümet kuruluşlarından biri tarafından kullanılmasının dışında.
Bu koda gömülü olan "değişiklik günlükleri" özellikle saftır. Sadece revizyonları farklılaştırdığınızda ve gerçekten umursadığınız bir fark olarak ortaya çıkıyorlar. VCS'nize güvenin - çoğu, kimin neyi değiştirdiğini çok hızlı bir şekilde gösterecek bir "suçlama" özelliğine sahiptir.
Tabii ki gerçekten korkunç olan şey, eski VCS'lerin gerçek VCS günlüğünün kaynak dosyalara gömülü olabileceği "eski zaman" VCS'lerin özelliğiydi. Birleştirmeyi neredeyse imkansız hale getirdi.
Belirli taahhüt iletileri tarafından otomatik olarak doldurulur her proje için tek bir ChangeLog dosyası var.
Yerleşik ChangeLog yorumlarımız yok. Eğer yapsaydık onları kaldıracak ve onları ekleyen kişi ile bir "konuşma" olurdu. Bence kullandığınız araçları, özellikle vcs'yi anlamadığının göstergesi.
Günlükleri grep etmeyi kolaylaştıran kesinleştirme iletileri biçimimiz var. Ayrıca işe yaramaz veya belirsiz taahhüt mesajlarına da izin vermiyoruz.
Şahsen kod kaynak dosyasındaki değişiklik günlüklerinden nefret ediyorum. Bana göre, yaptığım herhangi bir değişikliğin birden fazla yerde yapılması gerektiğinden, yazılım mühendisliği ilkesini ihlal ediyormuş gibi geliyor. Değişiklik günlüğü bilgileri çoğu kez tamamen işe yaramaz ve önemsizdir. Benim düşünceme göre, kodu kontrol ettiğinizde yazılımdaki değişiklikler belgelenmelidir.
Ama ne biliyorum ...
Değişiklik günlüğünü kaynak kodunda tutma uygulamasının uygulanması üzerine bir değişiklik varsa, değişiklik günlüğünün sınıfın pulik API/arabirimini 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şikliklerin bir değişiklik günlüğüne kaydedilmesi bence sadece karmaşıktır. Ancak, bazen başkaları için herhangi bir şeyi bozmuş olabilecek herhangi bir değişiklikle ilgili olarak kaynak kod dosyasının üst kısmının belgelendirilmesini kontrol etmenin ne kadar kullanışlı olabileceğini görebilirsiniz. Değişikliğin API'yı nasıl etkileyebileceğine ve değişikliğin neden yapıldığına dair bir özet.
Öte yandan, mağazam öncelikle C # şeyler yapıyor ve API'mızı belgelemek için her zaman satır içi XML yorumlarını kullanıyoruz, bu nedenle genel API değişiklikleriyle ilgili belgeleri okumak akıllıca kullanmak kadar az ya da çok basit.
Kaynak dosyadaki bir değişiklik günlüğünde ısrar etmenin, makineye sadece gereksiz sürtünme eklediğini ve ilk etapta bir sürüm kontrol sisteminin uygulanmasının amaçlarından birini yendiğini düşünüyorum.
Çalıştığım son şirketin arkasında 17 yıllık geçmiş, gelişim ve yıllık güncellemeler bulunan bir yazılım vardı. Bir sürüm kontrol sisteminden diğerine yapılan tüm geçişler yorumları veya check-in notlarını korumaz. Ayrıca, bu yıllar boyunca tüm geliştiriciler check-in yorumları/notlarıyla tutarlılık göstermedi.
Kaynak koddaki yorumlarla, değişikliklerin arkeolojik tarihi kod olarak değil not olarak tutuldu. Ve evet, hala VB6 kodu gönderiyorlar.
Sürüm kontrolü, ekibinizdeki geliştiriciler doğru kullanıyorsa koddaki değişiklik günlüğü yorumlarını değiştirebilir.
Ekibiniz check-in sırasında yorum eklemiyorsa veya yararsız yorumlar bırakıyorsa, gelecekte aradığınız bilgileri bulmak oldukça zor olacaktır.
Mevcut şirketimde, her check-in işleminde bir 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 edilen her dosyayı ve ne zaman bırakıldığını yorumla birlikte bu sorun için görebilirsiniz. Oldukça kullanışlı.
Temel olarak, sürüm kontrolü sadece bir araçtır, ekibiniz aradığınız avantajları sağlayacak olan aracı kullanır. Takımdaki herkes, hata düzeltme izlemenin yanı sıra temiz kod revizyonları sağlamak için onu nasıl kullanacakları konusunda hemfikir olmalıdır.
Bu, VCS günlüklerinin kafa karıştırıcı olduğu ve VCS sistemlerinin ele alınmasının zor olduğu günlerden kalan bir şeydir (80'lerin arkasında bir yerde o günleri hatırlıyorum).
Şüpheniz tamamen doğrudur, bu yorumlar bir yardımdan çok bir engeldir ve herhangi bir modern VCS tam olarak aradığınızı bulmanıza izin verecektir. Tabii ki, siz (ve iş arkadaşlarınız) yakl. Tüm bu özelliklerin nasıl sürüleceğini öğrenmek 30-60 dakika (aslında, bu yorumların hala orada olmasının nedeni budur.
George ile (neredeyse) saklıyorum. Koddaki yorumlar, yalnızca kodun kendisinde hemen görünmeyen bir şeyi açıklarsa gerçekten haklıdır. Ve bu nadiren iyi kodda gerçekleşir. Kodunuzda çok sayıda yorum yapmanız gerekiyorsa, bu kendi kokusu ve "beni yeniden düzenleyin!" Diye bağırıyor.
Bunları hala saklı yordam kaynağına dahil ediyoruz, çünkü bir istemcide tam olarak hangi sürümün mevcut olduğunu bu şekilde 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ı içi derleme için istemcilere kaynak olarak dağıtılır.
Eski PowerBuilder kodumuz hala bunları kullanıyor, ancak bunun belirli peep'ler için bir konfor faktörü olduğunu düşünüyorum. Bu da dağıtım için derlenir, bu yüzden (IMO onlar gerekir) friggin VCS geçmişini kullanın.
SVN kullanıyorsanız, bunu yapmak zaman kaybıdır ve tamamen işe yaramaz.
SVN'nin suçlama işlevi vardır. Bu, belirli bir dosyadaki her satırı kimin ne zaman yaptığını size söyleyecektir.
Kimsenin bundan bahsetmediğine şaşırdım, ancak bunun lisans gereksinimlerine uymasının orijinal nedeni değil mi? Yani, bazı lisanslar dosyada yaptığınız herhangi bir değişikliğin dosyanın kendisine kaydedilmesi gerektiğini söylüyor?
Değişiklik günlüğü yorumları, sonraki bir geliştiricinin yeni gereksinimlerle ilgili daha iyi sorular sormasına yardımcı olduklarında kodda son derece yararlıdır. Bir geliştirici, örneğin, Fred'in bir gereksinimi karşılamak için Foo alanını 6 ay önce zorunlu kıldığı bir yorum gördüğünde, geliştirici Foo'yu isteğe bağlı hale getirmek için en son talebi uygulamadan önce bir soru sormaları gerektiğini bilir. Karmaşık sistemlerle uğraşırken, farklı paydaşların farklı öncelikleri ve farklı arzuları olacaktır. Değişiklik günlüğü yorumları, ileride sorunlardan kaçınmak için bu değiş tokuşlardan 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 tüm geçmişini kontrol ettiyse, kodda bu yorumların bulunması gereksiz olacaktır. Ancak bu hem bir iş akışı açısından çok gerçekçi değil - çoğu geliştirici doğrulama işlemini kimin eklediğini ve nedenini - ve bir teknoloji bakış açısından - araştırma sürecini araştırmadan değiştirecekti. msgstr "kod satırı bir satırdan diğerine taşınmışsa veya farklı bir sınıfa yeniden kaydedilmişse. Koddaki yorumların görülme olasılığı daha yüksektir ve daha da önemlisi, müteakip bir geliştiricinin, görünüşte basit bir değişikliğin bu kadar basit olmayabileceğini belirtmesini istemek daha olasıdır.
Bununla birlikte, koddaki değişiklik günlüğü yorumlarını nispeten nadir olmalıdır. Ben değişiklik kodu yorum her kod biraz refactored her zaman veya gerçek bir hata giderildiğinde ekleneceğini savunmuyorum. Ama orijinal gereksinimi "Foo isteğe bağlıdır" ve birisi gelir ve "aşağı akış işlem Çubuğu desteklemek için gerekli Foo gereklidir" için gereksinimi değiştirirse, bu kesinlikle bir yorum eklemeyi düşünür. Çünkü gelecekteki bazı kullanıcı/analistlerin aşağı yönlü Bar sürecinden ve Foo'nun gerekli olmasının nedeninden habersiz olma olasılığı vardır ve Foo'yu tekrar isteğe bağlı hale getirmeyi ve Bar işleminde baş ağrısına neden olmayı isteyecektir.
Ve bu, kuruluşların özellikle bir avuç geliştiriciye sahip küçük şirketlerden çok daha büyük şirketlere büyüdükçe sürüm kontrol sistemlerini bir miktar değiştirmeye karar verebileceğini düşünmeden önce. Bu taşıma işlemleri genellikle değişiklik günlüğü yorumlarının kaybolmasına neden olur - yalnızca koddaki yorumlar korunur.
Yorumlar bölümümüzde bir değişiklik günlüğü tutmaya devam etmemizin nedeni kullanım kolaylığı içindir. Genellikle bir sorunu ayıklarken dosyanın üst kısmına kaydırmak ve değişiklik günlüğünü okumak, kaynak kontrol dosyasını açmak, içindeki dosyayı bulmak ve yapılan değişiklikleri bulmaktan daha kolaydır.