Yorum yazma ve dokümantasyondaki en iyi uygulamalar

Bugünlerde yorum yapmak her zamankinden daha kolay. Java'da, yorumları sınıflara bağlamak için bazı güzel teknikler vardır ve Java IDE'leri sizin için yorum kabukları yapmakta iyidir. Clojure gibi diller, işlev kodunun kendisinde bir işlevin açıklamasını bağımsız değişken olarak eklemenize izin verir.

Bununla birlikte, hala iyi geliştiriciler tarafından yazılan eski veya zayıf yorumların olduğu bir yaşta yaşıyoruz - Yorumlarımın sağlamlığını ve kullanışlılığını iyileştirmekle ilgileniyorum.

Özellikle burada Java / Clojure / Python ile ilgileniyorum, ancak cevapların dile özgü olması gerekmez.

Yorumları doğrulayan ve otomatik olarak "dayanıksız" yorumları (örneğin, sihirli sayılar, eksik cümleler vb.) Veya yanlış yorumları (örneğin, yanlış yazılmış değişkenleri veya benzerlerini algılama) algılayan herhangi bir yeni teknik var mı?

Ve daha da önemlisi: Kabul edilmiş "yorum politikaları" veya stratejileri var mı? Kodlama konusunda çok sayıda tavsiye var - ama "nasıl yorum yapılır?"

• İsimler / belgeler size ne yaptığınızı söylemelidir .

• Uygulama size bunu nasıl yaptığınızı söylemelidir .

• Yorumlar size bunu neden yaptığınız şekilde söylemelidir .

Bu tartışmalı olabilir, ancak tavsiyem mümkün olduğunca FEW yorumları yazmak olacaktır. Bunun yerine güzel, açık sınıf adları, değişken adları ve yöntem adları kullanın. Kodunuzu olabildiğince açık bir şekilde yazın; ve bunu kodunuzun en önemli özelliği olarak kabul edin (gereksinimlerini karşılaması dışında). Yalnızca mümkün olduğu kadar açık bir yöntem yaptıysanız ve yine de daha fazla açıklama gerektirdiğini düşünüyorsanız yorum yazın.

Ve herhangi bir şekilde bir sınıfı değiştirdiğinde, yorumların hala doğru olduğundan emin olmak zorunda oldukları örgütsel bir pratiğe sahip olun.

Diğer dillerden emin değilim, ancak python , kendini doğrulayan bir yorum türü olan doctestler yazmanıza izin veriyor . Tabii ki, gerçek birim testi yerine kullanılmamalıdırlar, ancak olması gerektiği kadar açık olmayan belirli işlevleri belgelemek için hızlı ve kolay bir yöntemdir. Yorumların hala doğru olduğunu (en azından test içeren kısmı) doğrulamak için yorum testlerini yürütebilmenin ek bir yararı vardır.

Belgeyi otomatik olarak oluşturmak için kod yorumunun nasıl kullanılacağını bulmak için en yetkili yerlerden biri kesinlikle doxygen'tir . Yine de bu tür araçlardan daha fazla olabilir.

Bu, belgeleri otomatik olarak oluşturmak için izlenmesi gereken yorum yazma standardını tanımlar . Bununla birlikte, bu daha fazla yapı verir, ancak anlamsal olarak doğrulamaz; örneğin bir fonksiyonun amacını tanımlamak için yanıltıcı ingilizce kullanıp kullanmadığınızı kontrol edemez!

Bu yorum yapılandırılmış kılan en iyi şey olsa da, şahsen ben kod gibi daha sürdürülebilir hale getirmek için gerekli daha fazla belge olduğunu hissediyorum. Bir süre önce P.SE'de bir soru vardı. Kod açık kaynak geliştirici araçlarındaki belgeler olabilir mi? Ne sıklıkla? Tabii ki, bu açık kaynaklı olmayan projeler için de geçerlidir.

Kodu daha sürdürülebilir hale getirmek için - kodun nasıl ele alınacağının yapısının oluşturulmasına yardımcı olan harici bir dokümantasyonun bulunması ve kodun içindeki yorumların görülmesi kısıtlanmalıdır.

Yorum yazmak için politikaları tanımlamak istiyorsanız , kodlama standardında yer alan bütünsel bir yaklaşım olarak yer almalısınız. Şuna bakın: Bir geliştirme ekibinde bir stil rehberi ve dokümantasyon yazılımı oluşturma konusunda bazı sorunlar neler olabilir?

Genellikle bir yorum, kodun% 5'inden daha azını oluşturur. Ve uygulamada, kod incelemelerinin kendisi daha az dikkat çekerken (gelişimin diğer yönlerine göre) yorumların da gözden geçirilmesi pratik olarak zordur.

Yorumları doğrulayan ve otomatik olarak "dayanıksız" yorumları (örneğin, sihirli sayılar, eksik cümleler vb.) Veya yanlış yorumları (örneğin, yanlış yazılmış değişkenleri veya benzerlerini algılama) algılayan herhangi bir yeni teknik var mı?

İyi bilinen bir teknik var - buna "kod inceleme" denir ve "çift programlama" adında bir kız kardeşi vardır. Burada "otomajik" bir şey beklemeyin.

Ve daha da önemlisi: Kabul edilmiş "yorum politikaları" veya stratejileri var mı? Orada nasıl kod --- hakkında tavsiye bol ama ama "nasıl yorum?"

"Kod tamamlandı" yalnızca kodlamanın nasıl yapılacağı hakkında değil, aynı zamanda "nasıl yorum yapılacağı", özellikle de kendi kendini belgeleyen kodun nasıl yazılacağı ile ilgili bölümleri de içerir.

Ben memnun kaldım Java bir kaynağa Özgül Oracle'ın olan Javadoc Aracı için Doc yaz nasıl :

Bu belgede, Java Software, Sun Microsystems'da yazılmış Java programlarının dokümantasyon yorumlarında kullandığımız stil kılavuzu, etiket ve görüntü kuralları açıklanmaktadır.

Ve Madde 44: Tüm açık API öğeleri için doc yorumları yazın :

Bir API kullanılabilirse, dokümante edilmelidir. Geleneksel olarak API belgeleri manuel olarak oluşturuldu ve kodla senkronize tutulması bir işti. Java programlama ortamı bu görevi Javadoc yardımcı programıyla kolaylaştırır. Javadoc, daha yaygın olarak doc yorumları olarak bilinen özel olarak biçimlendirilmiş belge yorumlarıyla kaynak belgelerinden otomatik olarak API belgeleri oluşturur.

dan Etkili Java 2nd Edition .