Kendini belgeleyen kod mu Javadocs mu?

Son zamanlarda şu anda uğraştığım kod tabanının parçalarını yeniden düzenleme üzerinde çalışıyorum - sadece kendimi daha iyi anlamak için değil, aynı zamanda kod üzerinde çalışan diğerleri için de daha kolay hale getirmek için.

Kendini belgeleyen kodun güzel olduğunu düşünmeye eğilimliyim . Sadece daha temiz olduğunu düşünüyorum ve kod kendisi için konuşursa, iyi ... Bu harika .

Öte yandan javadocs gibi belgelere sahibiz. Ben de bunu seviyorum, ama burada yorumların modası geçmiş (ve genel olarak yorumlar) belirli bir risk var. Bununla birlikte, eğer güncel iseler, karmaşık bir algoritmayı anlamak için son derece yararlı olabilirler.

Bunun için en iyi uygulamalar nelerdir? Kendi kendini belgeleyen kod ve javadoklar arasındaki çizgiyi nerede çiziyorsunuz?

Kendini belgeleyen kod (ve kod içi yorumlar) ve Javadoc yorumları iki farklı hedef kitleye sahiptir.

Kod dosyasında kalan kod ve yorumlar geliştiriciler içindir. Onların kaygılarını burada ele almak istersiniz - kodun ne yaptığını ve kodun neden böyle olduğunu anlamayı kolaylaştırın. Yorumlarla birlikte uygun değişken isimlerinin, yöntemlerinin, sınıflarının vb. Kullanımı (kendi kendini belgeleyen kod) bunu sağlar.

Javadoc yorumları genellikle API kullanıcıları içindir. Bunlar aynı zamanda geliştiricilerdir, ancak sistemin iç yapısını, sadece sistemin sınıflarını, yöntemlerini, girişlerini ve çıktılarını umursamazlar. Kod bir kara kutu içinde bulunur. Bu yorumlar, belirli görevlerin nasıl yapılacağını, operasyonların beklenen sonuçlarının ne olduğunu, istisnalar atıldığında ve girdi değerlerinin ne anlama geldiğini açıklamak için kullanılmalıdır. Javadoc tarafından oluşturulan bir dizi belge göz önüne alındığında, kodunuzun bir satırına bakmadan arayüzlerinizi nasıl kullanacağınızı tam olarak anlayabilmeliyim.

Kod nasıl söylüyor . Yorumlar neden ve hatta neden olmasın .

Kodunuzun gelecekteki okuyucularına ve bakımcılarına sunmak sizin işinizdir. Kodda mümkün olan her şeyi ve geri kalanları yorumlarda belirtin.

Yakalanması en zor şeylerin tasarım kararları olduğunu unutmayın - bunları da unutmayın.

Javadocs kullanmak gerçek bir fark yaratmaz - oluşturulan dokümanlar işlevlerin adını yorum metniyle birlikte içerdiğinden, yorumlarda işlev adının kendisinden net olan herhangi bir şeyi tekrarlamanızın kesinlikle bir nedeni yoktur.

Öte yandan, kişinin neyin iyi olduğunu anlamak için uygulamaya bakması gereken bir işleviniz varsa (bu nedenle bu bilgileri Javadocs için kullanılabilir hale getirmezse), kod ne olursa olsun IMHO'dur. uygulamanın ne kadar net olduğu.

Ben javadocs ile, işler herhangi bir belge ile aynı olduğunu düşünüyorum - ana kural:

izleyiciyi takip et

Do birçok kişi sizin javadocs okumak? Evet ise, bunu düzeltmek için çaba harcamak mantıklıdır.

Okurlarınız javadokları incelemek için okuma kodunu atlama eğiliminde mi? Evet ise, iyi yazmak için çaba harcamak iki kat daha mantıklıdır.

• JDK dokümantasyonunda durum böyledir . Sanırım Sun / Oracle bunlar üzerinde çok çaba harcadı ve API belgelerinde topluluk tarafından çok kullanılan güzel bir geri ödeme var gibi görünüyor.

Şimdi, senin durumun mu? Değilse, javadoklara yapılan çabaların haklı olup olmadığını iki kez düşünün.

Yukarıda belirtildiği gibi, yolu bulmak için dinleyicileri dinleyin .

• Yetersiz dokümantasyon hakkında aktif şikayetler duyarsanız, iyileştirmeye yatırım yapmayı düşünün.
   
  Öte yandan, duyduğunuz tek şey, onları işe yaramaz yazarak zaman kaybetmeye zorlayan braindead kuralları hakkında sızlanan geliştiriciler ise, o zaman javadocs çabalarınızın subprime ipoteklere yatırım yapmak gibi olma ihtimali yüksektir . Bunun yerine daha iyi yatırımlar düşünün.

Sadece Javadoc yorumlarının modası geçmiş olabileceği endişesi hakkında yorum yapmak istiyorum. @JonathanMerlet, Javadoc'un kararlı olması gerektiğini söylerken haklı olsa da, akran incelemesi sırasında Javadoc ve yorumları ve kodu inceleyerek de yardımcı olabilirsiniz. Yorumlar kodun yaptığı ile eşleşiyor mu? Değilse, bu yanlıştır ve geliştiricinin düzeltmesi için ısrar eder. Diğer geliştiricileri de aynısını yapmaya teşvik etmeye çalışın. Bu, yalnızca harici belgelerin (Javadoc yorumları) güncel kalmasını değil, aynı zamanda normal kod yorumlarını da güncel tutmanıza yardımcı olur. Bu, yeniden düzenleme işleminizden sonra gelen geliştiricilerin kodu daha hızlı ve kolay bir şekilde anlamalarına yardımcı olur ve gelecekte de bunu daha basit hale getirir.

Javadocs'un sabit kalması gereken parçalar (API) için uygun olduğunu düşünüyorum, böylece yorumların güncelliğini kaybetme riski en aza indirilirken, kendini belgeleme kodu sık sık değişime (uygulama) tabi olan için harika. Elbette, API'ler proje sırasında değişebilir, ancak açıklamadan hemen önce başlığa sahip olmak, her ikisini de senkronize tutmak o kadar da zor değildir (birkaç satır satırını açıklayan birden fazla satırdaki yorumlarla karşılaştırıldığında)