Kod bakımı: Kodda yorum eklemek veya sürüm denetlemesinde bırakmak için mi?

Bir hatayı düzeltmek / bir CR uygulamasının bir parçası olarak koda yaptığımız her değişiklik için başlangıç ​​etiketleri, son etiketleri, açıklama, çözüm vb.

Benim endişem, bu herhangi bir katma değer sağlıyor mu? Olduğu gibi, Versiyon kontrol geçmişinde her bir değişikliği izlememize yardımcı olacak tüm detaylara sahibiz?

Ancak benim ipuçlarım yorumların "iyi" bir programlama uygulaması olarak yapılmasında ısrar ediyor. Argümanlarından biri, bir CR'nin kapsamdan çıkarılması / değiştirilmesi gerektiğinde, yorumlar orada değilse hantal olur.

Değişikliklerin büyük ölçüde kodlar arasında olacağı göz önüne alındığında, yaptığımız her değişiklik için yorum eklemek gerçekten yardımcı olur mu? Sürüm kontrolüne bırakmamalı mıyız?

Kesinlikle haklısın. Değişiklikleri izlemek, sürüm kontrol sisteminizin işidir. Ne zaman bir taahhütte bulunursanız, ne yapıldığını açıklayan ve bu bir hata düzeltmesi ise hata izleme sisteminize referans veren bir taahhüt mesajı yazmalısınız. Kodda bir yorum koymak söyleyerek

// begin fix for bug XXXXX on 10/9/2012
...
// end fix for bug XXXXX

bir hatayı her düzeltdiğinizde, kodunuzu hızla okunamaz ve ulaşılamaz hale getirir. Aynı zamanda, aynı bilginin iki yerde çoğaltılmasıyla sonuçlanacak ve bu da karışıklığı daha da kötüleştirecek.

Yorumlar hata izleme için kullanılmamalı ve ayrıca kodunuzun ne yaptığını açıklamamalıdır. Neden X yaptığını ya da neden bu şekilde X yaptığını açıklamalılar. Bir kod bloğunun ne yaptığını açıklayan bir yorum yazma gereği duyuyorsanız, bu bloğu tanımlayıcı bir ada sahip bir işlev haline getirmeniz gerektiğini belirten bir kod kokusudur.

Yani yerine

// fixed bug XXXXX on 10/9/2012

yazan bir yorumunuz olabilir

// doing X, because otherwise Y will break.

veya

// doing X, because doing Y is 10 times slower.

İş için en iyi aracı kullanın. Sürüm kontrol sisteminiz , hata düzeltmeleri ve CR'ler yapıldığında kayıt için en iyi araç olmalıdır : tarihi otomatik olarak kaydeder ve değişikliği kim yapar; bir mesaj eklemeyi asla unutmaz (eğer bunu taahhüt mesajları gerektirecek şekilde yapılandırdıysanız); asla yanlış kod satırına açıklama eklemez veya bir yorumu yanlışlıkla siler. Sürüm kontrol sisteminiz zaten yorumlarınızdan daha iyi bir iş yapıyorsa, yorum ekleyerek işi çoğaltmak aptalcadır.

Kaynak kodun okunabilirliği çok önemlidir. Yapılan her hata düzeltmesinin tam tarihini ve yorumunu veren yorumlarla dolu bir kod temeli ve CR hiç okunaklı olmayacak.

Ancak yorumları eksiksiz bir şekilde atlamayın: İyi yorumlar (her bir düzeltmenin ve CR'nin her start / stop / açıklama / çözümünü kasten belgelemek değil) kodun okunabilirliğini arttırır. Örneğin, bir hatayı düzeltmek için eklediğiniz zor veya net olmayan bir kod biti için, form // fix ISSUE#413izleyicisine, sorun izleyicinizde daha fazla bilgiyi nerede bulacağınızı söyleyen bir yorum mükemmel bir fikirdir.

Kodunda Yorumlar kodu nedir üzeresiniz olduğunu o an. Herhangi bir zamanda anlık görüntü almak, kodun eski (veya daha kötü, gelecek) sürümlerine atıfta bulunmamalıdır.

VCS'deki yorumlar kodun nasıl değiştiği ile ilgilidir. Gelişim hakkında bir hikaye olarak okumalıdırlar.

Şimdi, her değişiklik yorum içermeli mi? çoğu durumda, evet. Hayal ettiğim tek istisna, beklenen davranışın zaten belgelendiği, ancak bir hata nedeniyle elde ettiğiniz şey olmadığı zamandı. Bunu düzeltmek, mevcut yorumları daha kesin hale getirir, bu nedenle değiştirilmeleri gerekmez. Hatanın kendisi, bilet geçmişinde ve kesin yorumunda belgelenmelidir, ancak yalnızca kod tuhaf görünüyorsa kodda belgelenmelidir. Bu durumda, bir // make sure <bad thing> doesn't happenyeterli olmalı.

Gerçekten takdir ettiğim bir yorum türü:

// Bu, 2. Teklifin İş Kuralı için uygulanmıştır

veya gereksinimlerinizi karşılamak için ne halt kullanıyorsanız kullanın.

Bunun iki avantajı vardır; bunlardan biri, arama yapmadan verilen bir algoritmayı uygulamanızın nedenini bulmanızı sağlarken diğeri de, gereksinim belgeleri üzerinde çalışan / bunları oluşturan yazılım dışı mühendislerle iletişim kurmanıza yardımcı olacaktır.

Bu, daha küçük ekiplerde yardımcı olmayabilir, ancak gereksinimlerinizi geliştiren analistler varsa, bu paha biçilmez olabilir.

Müşterileriniz, yorumların iyi bir programlama uygulaması olduğunu söylediklerinde haklılar, ancak istisnalar da var. Yaptığınız her değişiklik için bir yorum eklemek bunlardan biridir. Ve bunun sürüm kontrol sistemine ait olması gerektiğini söyleyerek haklısınız. Bu yorumları tek bir yerde tutmanız gerekiyorsa, VCS gitmenin yolu budur. Kaynak kodundaki yorumlar yaşlanma ve bakımsız kalma eğilimindedir. Hiçbir yorum kötü yorumlardan çok daha iyi değildir. İstemediğiniz şey, her iki yerde de (kod ve VCS'de) senkronize olmayan yorumlar yapmaktır. Amaç, koddaki değişiklikler için tek bir doğruluk kaynağına sahip olarak DRY'yi saklamaktır.

Başkalarının söylediklerine ek olarak, bir değişiklik sistemde dalgalanmalara neden olursa ne olacağını düşünün. Bir değişiklik isteği uygulama sürecinde çekirdek bir arayüzün bir bölümünü yeniden adlandıracağınızı söyleyin - bu tür bir değişiklik, önemsiz değişikliklerin (sınıf veya yöntem adı değişir). Böyle bir işlemle dokunulan her dosyayı gözden geçirerek VCS'ye otomatik olarak yapmaktan ziyade, bu yorumlarla manuel olarak açıklama yapmanız mı gerekiyor? Bir durumda, herhangi bir uygun yeniden yapılandırma aracıyla beş dakikadan daha az bir işe bakıyorsunuz ve ardından hiçbir şeyin yapıyı bozmadığından emin olmak için bir yeniden derleme yapıyorsunuz, diğeri ise kolayca bir günün işine giriyor. Hangi özel yarar için?

Ayrıca kodun bölümlerini hareket ettirdiğinizde ne olacağını da göz önünde bulundurun. Çalıştığım veritabanı geliştiricilerinden biri büyük ölçüde kampında "değiştirilen revizyona her SQL satırı eklenmiş olmalı ve her dosya için ayrı revizyon geçmişi yapacağız çünkü daha sonra görmek daha kolay olacak Kim neyi ne zaman ve niçin değiştirdi ". Bu tür bir sorta çalışır, değişim ne zaman olurtek satır değiştirme sırasına göre. Son zamanlarda ciddi bir performans sorununu çözmek için yaptığım gibi, geçici tabloları tanıtan daha büyük bir sorgunun parçalarını kırıp, ardından yeni kod akışına daha iyi uyması için bazı sorguların sırasını değiştirdiğinizde de pek işe yaramaz. Kabul edilirse, önceki sürüme karşı fark, dosyanın üçte ikisinin değiştiğini söylediğinden büyük ölçüde anlamsızdı, ancak check-in yorumu da "performans sorunlarını düzeltmek için büyük yeniden yapılanma" gibi bir şeydi. İki versiyona manuel olarak baktığınız zaman, büyük parçaların gerçekten aynı olduğu, sadece dolaştığı oldukça açıktı. (Ve söz konusu saklı işlemi düzenli olarak yürütmek yarım dakikadan birkaç saniyeye kadar sürdü.

Çok az istisna dışında, izleme takibi ve konuya atıfta bulunma VCS, IMNSHO'nun eseridir.

Genelde bu kuralı izlerim: eğer değişiklik açıksa ve sonuçta ortaya çıkan kod soru sormazsa, önceki davranışları önemli ölçüde değiştirmezse, büyük ölçüde değiştirmezse - o zaman hata numaralarını ve diğer değişiklik bilgilerini izlemek için VCS'ye bırakın.

Bununla birlikte, eğer açık olmayan bir değişiklik varsa, mantığı değiştirir - özellikle başkası tarafından yapılan mantığı belirgin olmayan bir şekilde değiştirirse - "bu değişiklik bunu yapmaktır. 42742 numaralı hata yüzünden. Bu şekilde birileri koduna baktığında ve "neden burası burada? Bu garip görünüyor" diye merak ettiğinde, onun önünden bir rehberlik hakkı vardır ve VCS aracılığıyla soruşturma yapmak zorunda kalmaz. Bu aynı zamanda insanların diğerlerinin değişikliklerini bozduğu durumları da önler, çünkü kodun eski durumuna aşinalar ancak o zamandan beri değiştiğini farketmemişler.

Sürüm kontrolü ile ilgili yorumlar kaynak dosyaya ait değildir. Sadece karmaşa katarlar. Muhtemelen aynı yere yerleştirilmeleri gerektiğinden (dosyanın üst kısmındaki bir yorum bloğu gibi) paralel dallar birleştirildiğinde yalnızca yorum dışı rahatsızlık çatışmalarına neden olurlar.

Sürüm kontrolünden çıkarılabilecek herhangi bir izleme bilgisi kodun gövdesinde çoğaltılmamalıdır. Bu RCS ödeme anahtar kelimeleri gibi $Log$ve aptalca fikirler için ilk ve onun gibi gider .

Kod, sürüm kontrol sisteminin kapsamı dışına çıkarsa, geçmişi hakkındaki yorum izleri bağlamı ve dolayısıyla değerinin çoğunu kaybeder. Değişikliğin tanımını doğru bir şekilde anlamak için, revizyona erişmemiz gerekir, böylece farklılığı önceki sürüme göre görebiliriz.

Linux çekirdeğindeki bazı eski dosyaların büyük tarih yorum blokları vardır. Bunlar sürüm kontrol sistemi olmadığı zamanlara dayanır, sadece tarball'lar ve yamalar.

Koddaki yorumlar asgari ve doğru olmalıdır. Hata / değişiklik bilgisi eklemek değerli değil. Bunun için sürüm kontrolünü kullanmalısınız. Bazı zamanlar Sürüm kontrolü biraz daha iyi bir değişim yolu sağlıyor; ClearCase UCM kullanıyoruz; UCM faaliyetleri, hata numaraları, değişim alanı vb. Esas alınarak yaratılır (örn. Hata 29844_change_sql_to_handle_null).

Check-in yorumlarında detaylı yorumlar tercih edilmektedir.

Bazı yan etkiler nedeniyle arkaplan bilgisi, uygulanamayan çözümün detayları hakkında bilgi vermeyi tercih ederim.

Pramagic Programmer ve CleanCode aşağıdaki kılavuza yönlendirir

Düşük düzeyli bilgiyi ait olduğu kodda tutun ve diğer yüksek düzey açıklamalar için yorumları saklayın.