Genellikle bu tür yorumları kötü bir uygulama olarak görüyorum ve bu tür bilgilerin SCM taahhüt günlüklerine ait olduğunu düşünüyorum. Çoğu durumda kodun okunmasını zorlaştırır.
Ancak , yine de belirli türdeki düzenlemeler için böyle bir şey yapıyorum.
Durum 1 - Görevler
Eclipse, Netbeans, Visual Studio gibi bir IDE kullanıyorsanız (veya kod tabanınızda başka bir şeyle metin araması yapmanın bir yolu varsa), ekibiniz bazı özel "yorum etiketleri" veya "görev etiketleri" kullanır. Bu durumda bu yararlı olabilir.
Zaman zaman, kodu incelerken, aşağıdaki gibi bir şey eklemek istiyorum:
// TOREVIEW: [2010-12-09 haylem] marking this for review because blablabla
veya:
// FIXME: [2010-12-09 haylem] marking this for review because blablabla
Bunun için görev görünümünde Eclipse'de görebildiğim farklı özel görev etiketleri kullanıyorum, çünkü taahhüt günlüklerinde bir şey olması iyi bir şeydir, ancak bir inceleme toplantısında size bir hata giderme XY'nin neden tamamen unutulduğunu soran bir yöneticiniz olduğunda yeterli değildir. ve geçip gitti. Acil konularda veya gerçekten şüpheli kod parçalarında, bu ek bir hatırlatma görevi görür (ancak genellikle yorumu kısa tutacağım ve taahhüt günlüklerini kontrol edeceğim çünkü bu hatırlatma için buradadır, bu yüzden kodu da karıştırmıyorum çok).
Durum 2 - 3. Taraf Libs Yamaları
Ürünümün üçüncü taraf bir kod parçasını kaynak (veya kitaplık olarak paketlemesi gerekiyor, ancak kaynaktan yeniden oluşturulmuş) bir nedenden dolayı yamalanması gerekiyorsa, yamayı bu "uyarıları" listelediğimiz ayrı bir belgede belgeliyoruz. ileride başvurmak için kullanılır ve kaynak kodu genellikle aşağıdakine benzer bir yorum içerir:
// [PATCH_START:product_name]
// ... real code here ...
// [PATCH_END:product_name]
Durum 3 - Belirsiz Düzeltmeler
Bu biraz daha tartışmalı ve kıdemli geliştiricinizin istediklerine daha yakın.
Şu anda üzerinde çalıştığım üründe, bazen (kesinlikle ortak bir şey değil) aşağıdaki gibi bir yorumumuz var:
// BUGFIX: [2010-12-09 haylem] fix for BUG_ID-XYZ
Bunu yalnızca bugfix belli değilse ve kod anormal okursa yaparız. Bu, örneğin tarayıcı tuhaflıkları veya yalnızca üründe bir belge hatası olduğu için uygulamanız gereken belirsiz CSS düzeltmeleri için geçerli olabilir. Bu nedenle, genel olarak, dahili sorun depomuza bağlarız, bu da daha sonra hata düzeltmesinin arkasındaki ayrıntılı mantığı ve harici ürünün hatasının belgelerine işaret eder (iyi bilinen bir Internet Explorer 6 hatası için bir güvenlik danışma belgesi veya bunun gibi bir şey).
Ancak belirtildiği gibi, oldukça nadirdir. Görev etiketleri sayesinde, düzenli olarak bunları gözden geçirebilir ve bu garip düzeltmelerin hala mantıklı olup olmadığını veya aşamalı olarak kaldırılıp kaldırılamayacağını kontrol edebiliriz (örneğin, hataya neden olan buggy ürün için desteği düşürdüğümüzde).
Bu sadece: Gerçek bir hayat örneği
Bazı durumlarda, hiç yoktan iyidir :)
Kod tabanımda, başlık yorumunun her zamanki yadda yadda ile bir değişim günlüğü şeklinde olduğu büyük bir istatistiksel hesaplama sınıfıyla karşılaştım: inceleme, tarih, hata kimliği.
İlk başta hurdaya çıkarmayı düşündüm, ancak hata kimliklerinin sadece mevcut sayı izleyicimizin kurallarına uymadığını, aynı zamanda şirkete katılmadan önce kullanılan izleyiciden biriyle eşleşmediklerini fark ettim. Bu yüzden kodu okumaya ve sınıfın ne yaptığını (bir istatistikçi değil) anlamaya çalıştım ve ayrıca bu hata raporlarını kazmaya çalıştım. Oldukça önemliydi ve küçük müşterinin sorunları ve o zamanki menşe müşteri tarafından yayılan çok özel gereksinimlere dayanan özel durumlar ile uğraştığı için dosyayı oldukça korkunç bilmeden düzenlemek için bir sonraki adamın hayatına bakacaklardı. . Sonuç olarak, eğer bunlar orada olmasaydı, bilemezdim. Eğer orada olmasaydı VE sınıfı daha iyi anlamış olsaydım,
Bazen bunlar gibi çok eski gereksinimleri takip etmek zor olabilir. Sonunda yaptığım hala başlığı kaldırmak oldu, ama her suçlayıcı fonksiyondan önce bir blok yorumda gizlice girdikten sonra neden bu "garip" hesaplamalar özel istekleri olarak açıklayan.
Bu durumda hala kötü bir uygulama olarak görüyordum, ama oğlum orijinal geliştiricinin en azından onları yerleştirdiği için mutluydum! Kod yerine açıkça yorum yapmak daha iyi olurdu, ama sanırım bu hiçbir şey daha iyi oldu.