Yorumlar bir tür belge olarak kabul ediliyor mu?

Kendim için küçük komut dosyaları yazarken, kodlarımı yüksek yorumlarla yığarım (bazen ben koddan daha fazla yorum yaparım). Konuştuğum bir çok insan, kişisel olmasına rağmen bu senaryoları belgelemem gerektiğini söyledi, böylece onları satarsam hazır olurdum. Ancak yorumlar bir tür dokümantasyon değil mi?

Bu olmaz:

$foo = "bar"; # this is a comment
print $foo; # this prints "bar"

özellikle bir geliştirici kodumu kullanıyorsa, belgeler dikkate alınmalıdır? Yoksa belgelerin kodun dışında olduğu düşünülüyor mu?

Yorumlar kesinlikle dokümantasyon. Çoğu proje için yorumlar maalesef proje belgelerinin birincil (sadece değil) biçimidir. Bu nedenle, doğru yapmak çok önemlidir. Kod değişikliklerine rağmen bu belgelerin doğru kaldığından emin olmanız gerekir. Bu, yorumlarda sık karşılaşılan bir sorundur. Geliştiriciler, tanıdık bir kodda çalışırken genellikle onları "ayarlar", bu nedenle yorumları kodu yansıtacak şekilde güncellemeyi unuturlar. Bu, eski ve yanıltıcı yorumlar oluşturabilir.

Birçok kişi kodu kendi kendine belgelemeyi önerir. Bu, yorumlar yerine kodunuzu bunlara olan ihtiyacı ortadan kaldırmak için yeniden yapılandırdığınız anlamına gelir. Bu, "ne" ve "nasıl" yorumlarının çoğundan kurtulabilir, ancak "neden" yorumlarına gerçekten yardımcı olmaz. Bu, çoğu yorumdan kurtulmak için etkili bir şekilde çalışabilse de, bir yorum yazmanın bir parça kodu belgelemenin en basit ve en etkili yolu olduğu birçok zaman vardır.

Bunlar bir belge biçimidir, ancak belgelerin izleyicinin gözünde olduğunu unutmayın.

• Bazıları için kendi kendini belgeleyen kod yeterlidir. Ancak bu, müşteri olarak bir miktar teknik detayı varsayar. Bunun yeterli olduğunu düşünmeye dikkat etmeliyiz, çünkü egomuz bize "Bu kodun ne yaptığı açıktır" ama zaman aksini ispatlayabilir. Ayrıca, okuyucunun becerilerini önceden bildiğinizi varsayar.

• Kaynak koduna bakanlar ancak daha az teknik uzmanlığa sahip olanlar için yorumlar iyi olabilir. Ancak bu, birinin kaynak koduna baktığını varsayar.

• Teknik iseniz, ancak tüm kaynak kodunu okumak için zamanınız yoksa, teknik bir kılavuz gerekli olabilir.

• Kullanıcı teknik becerilere sahip değilse, ancak ne olduğunu bilmeye ihtiyaç duyuyorsa, kullanıcı dokümantasyonu neye ihtiyaç duyduğudur.

Asıl soru müşterinizin kim olduğu. Eğer öyleyseniz, kod veya yorumları kendiniz belgelemek yeterlidir. Başka biri içinse, dokümantasyonunuzu genişletmek isteyebilirsiniz.

Evet, yorumlar bir belge biçimidir. Kodunuzu korumak veya güncellemek zorunda olan biri için yararlı belgeler olup olmadıkları açık bir sorudur.

Bunu bir örnek olarak kastettiğini biliyorum, ama

print $foo; # this prints "bar"

yararlı değil; sadece görsel karmaşa ekler. Açık olanı belgelemeyin.

Bir yöntemin veya işlev tanımının başındaki, işlevi veya yöntemin amacını ( üst düzey terimlerle) tanımlayan yorumları , girişleri, çıkışları, dönüş değerini (varsa), istisnaları (varsa), önkoşulları ve sonkoşulları yararlı, ancak birisine fonksiyonun veya yöntemin nasıl kullanılması gerektiğini söyleyecek derecede. İşlevin neden var olduğunu açıklamazlar .

Başkasının ihtiyaçlarını kodunuzu korumak için, o zaman gereksinimleri ve tasarım bir yerlerde belgelemek gerekiyor ve bu en tipik değil kaynak kodunun kendisinde yapılır.

Bob Martin'in bu yaklaşımına bağlı kaldığımı, Temiz Kod'dan, genellikle fazla yorum yaptığınızı veya yorum yazdığınızı veya belgeleri bıraktığınızı düşünüp düşünmediğinizi çözer:

Biz yazarız. Yazarlar hakkında bir şey okuyucularının olması. Gerçekten de, yazarlar okurlarıyla iyi iletişim kurmaktan sorumludur. Bir sonraki kod satırını yazdığınızda, çabanızı değerlendirecek okuyucular için yazan bir yazar olduğunuzu unutmayın.

... okumak ve yazmak için harcanan zamanın oranı 10: 1'in üzerindedir. Yeni kod yazma çabasının bir parçası olarak sürekli olarak eski kodu okuyoruz.

Başka bir deyişle, kodunuz dokümantasyon olmadan kendi kendini açıklıyor mu? Bunun için belirlenmiş bir kural yoktur (belgelerine herkesin erişebildiği Microsoft gibi biriyle çalışmıyorsanız), çoğunlukla kodun gelecekteki okuyucularına genellikle sizin olan yardımınıza bağlıdır.

Belgeler belgelemek gerekir Neden değil nasıl . Kodda nasıl açıkça görülmeli, yani bazı arcane optimizasyon hilesi veya yaygın olarak ortaya çıkmayan başka bir dile özgü teknik olmadığı sürece.

Neden muhtemelen bir değişiklik günlüğüne veya şube adına aranabilir hikaye kimlikleri ile yorumlarınızı işlemeye bağlı bir ürün birikim gibi başka bir yerde olmalı, kodu olmamalıdır.

Yorumlar bir belge türüdür. Daha düşük bir form ve kodunuzun daha iyi çarpanlarına ayrılabileceğiniz bir alan bulduğunuzu gösteren bir form.

Kulağa zorla yorum yaptığınız anlaşılıyor. Başka seçeneklere sahip olmak iyi bir şey olabilir. Üç üstün belge biçimini düşünebilirim:

1) Kodunuzu daha iyi faktörler. Yorum eklemek yerine, adı yazmak üzere olduğunuz yorumun metni olan bir yöntemi veya işlevi çıkarın. Kod, yorumunuzun ne hakkında olduğunu söylemektedir.

2) Testler. Bu genellikle aradığım dokümantasyon şeklidir. Birim testleri ve kabul testleri canlı belgelerdir ve 1. maddede olduğu gibi amacı ifade etmek için çok sayıda anlamlı yöntem kullanıldığında kolayca okunabilir.

3) Komut dosyaları için --help seçeneği. Doktor burada deli gidebilirsiniz. Örneklere sadık kalın, kullanıcının neye ihtiyacı olacağını tahmin edin.

Özet olarak, bir yorumda bulunmaya meyilli bulursanız, kodu daha iyi yapılandırarak okuyucu ile iletişim kurmanın bir yolu olup olmadığını kontrol edin. Yoksa bu kodun neden orada olduğunu bildiren bir test var mı? Hala yorum yapmaya eğilimli hissediyorsanız, yenilgiyi kabul edin ve yapın.