Her şeyi mi yoksa en çok belgelendirmeli mi?

Bu alanlar için Alıcı ve ayarlayıcıların "JavaBean" sözdizimi dahil belge her şeyi tartışmalı konu, biraz görünüyor: İnsanlar demek onun gereksiz uzun ve tekrarlayan kopma KURU (kendinizi tekrar etmeyin) , adlandırma kuralı açıklamak gerektiğini her şeyi , ve kod / dökümanları tutar. Bazen bu argümanlar işe yarar. Ama diğer zamanlarda, bununla bitiyorsun:

Yukarıda, bu ilkeleri cesurca izleyen açık kaynaklı projeler için yaygındır. Tamamen işe yaramaz belgelerle kaldın . Bu, altında neler olup bittiği, olası etkiler ve hatta beklenen değerin ne olduğu hakkında hiçbir şey açıklamıyor (boş veya hiç boş olamaz mı? Bilmiyorum; Javadoc bana söylemez).

Öyleyse ne zaman belgelemeliyim? Arada sırada kodlar olsa bile her şeyi belgeliyor muyum? Yoksa gözlerimin "bariz" olması nedeniyle hiçbir şey belgelendirmiyor muyum?

Belgelenmesi gereken her şeyi belgeleyin .

İdeal bir dünyada, evet, her şeyi belgelersiniz. Ancak, Dünya'da son tarihler, özellik kesintileri, ziyaret edilecek aileler ve arkadaşlar, tatiller, günde sadece 24 saat ve yılda sadece 365 gün var. Her şeyi belgelemek için yeterli zaman yok. Böylece, optimal olarak, yapabileceğiniz her şeyi belgeleyin (yapmazsınız), ancak paranın karşılığını en iyi şekilde alarak:

• Yap kod okunabilir ve mümkün olduğunca belirgin olarak yöntem imzaları bu belgeleyen bu yüzden daha az olasıdır ihtiyaç duyulacak.
• İlk önce en karanlık şeyleri belgelemek. Kapıdan bir şeyler çıkarmak için yapmanız gereken çılgın saldırıları belgeleyerek başkalarına yardım edin.
• Neden daha önce ne olduğunu belgeleyin - "Dengenin sıfırdan düşük ve derecelendirmenin birden az olduğu müşteri kayıtlarını yineleyin ve bunları muaf Müşteriler listesine ekleyin" gibi bir şeyin ne yaptığını yorumlamayın. Bunları neden listeye düz ingilizce (veya ekibinizin dilinde) eklediğinizi belgeleyin , "Bu müşteriler negatif bir bakiyeye ve düşük derecelendirmeye sahip olduklarından, para kaybetmemize neden oluyorlar, bu yüzden onları kontrol etmekten alıkoyun.

Herhangi bir şeyi açıklamaya gerek duymadan başkasının okumasını izleyene kadar belgelemeye devam edin.

Geçen hafta The Daily WTF’de dokümantasyon ile ilgili harika bir makale vardı. Sanırım her şeyi söylüyor, ben sadece bağlantıyı bırakacağım:

http://thedailywtf.com/Articles/Documentation-Done-Right.aspx

Temel olarak, eğer faydalı olmayacaksa (bazı belgeler çekmecede çürümeye bırakılır) bir şey belgelenmemesi ve projenin belirli bir bölümünü anlamak için gereken en az miktarda bilgiyi belgelemeniz gerektiğini söylüyor. Çok fazla belge sadece okuyucunun kafasını karıştırır.

Gerçekten de, kodun okunabilir kitleye ne kadar okunabileceğine bağlı. İzleyicinin kodunuzu okumak için kim olduğunu bulun ve bu profili karşılayan birisinin kodunuzu okumasını sağlayın.

Diğer bir yaklaşım, bir hafta sonra kendi kodunuzu gözden geçirmek ve ne yaptığınızı hala anlayıp anlamadığınızı anlamak, eğer yapmazsanız, onu belgelemek ve iki hafta içinde kodu incelemek olacaktır.

Açık ve kapsamlı bir belgeyi takdir etmeme rağmen, kendini belgeleyen kod gibisi yoktur. Yani, sonuç olarak (benim için):

(Kaynak kodu) dokümantasyonundan çok şüpheli olun; kodu geliştirerek onu gereksiz kılmaya çalışın, ancak gerektiğinde açıkça ve tamamen belgelenmekten çekinmeyin.

Tabii ki, belirli şartlar altında, 'kodun ne yaptığını açıklamak' dışındaki nedenler için dokümantasyon gerekebilir (örneğin: büyük takım tabanı, organizasyon standartları vb.).

Belgelendirme konusundaki önerim, kodda herhangi bir fantezi varsa, güncel tutulması gereken bir belgeye ait olmasıdır. Çok fazla yorumlamaya tabi olmaktan hoşlanıyorum, aklımda, belirtilmesi gereken yan etkileri olan belirli bir tarzda bir şeyin yapıldığı yer var, örneğin torunların bir düğüm ağacından geçerken işlenmesini sağlamak için tekrarlı bir şekilde yapılabilir. Tüm torunları üzerinde bir test yapmak için. Bir şeyin neden belirli bir şekilde yapıldığını açıklamak, bir şeyi kullanmak için iyi bir neden olup olmadığını bilmek için iyi bir yol olabilir.

Basit bir ifadeyle, dokümantasyon şimdi geliştiricilere ve gelecekteki bakımcılara yardım etmek için var.

Bu basit maxim'i hatırlarsanız, dokümantasyon seviyesi kendini tanımlamalıdır.

Dokümantasyon, dokümantasyon uğruna, zaman kaybıdır ... ama bugün yaptığınız şeyi açıklamak, birilerinin beş yıl içinde kodunuzu tersine çevirmek zorunda kalmasından daha yararlıdır.

Şahsen ben her şeyi belgeleme düşünmek yaklaşımı ile gitmek . Kodlama yaparken her noktada belgelerin değer katıp katmayacağını düşünüyorum. Çoğu zaman cevap, asıl soruda belirtilen sınırlama türleri ve alan bilgisi için evet. Boş yetenek, benzersiz kısıtlamalar, daha geniş alandaki alanın yorumlanması.

Çoğaltmayı önlemek için ana API sınıflarını bu tür bilgilerle yoğun şekilde belgeleme eğilimindeyim. O zaman sadece açık olmayan ya da tutarsız davranışların olduğu uygulamaları ve kurumları belgeleyin. Bunun en iyi yardıma ve belgeye ihtiyaç duyan API kullanıcıları olduğu için işe yaradığını düşünüyorum. Uygulamayı değiştiren kişilerin API'yi bildiklerini varsaymak genellikle güvenlidir, bu yüzden bu bilgiye sahiptir.

Ayrıca sadece alıcıları belgeleme eğilimindeyim. Belgeleri ayarlayıcılara, alan tanımlarına ve yapıcı parametrelerine kopyalamıyorum. Yalnızca bu yerlerdeki varsayılanlar gibi açıkça görülmeyen davranışları belgeliyorum. Alıcı belgelerinde çıkarılan herhangi bir davranış belgelenmemiştir. Örneğin, alıcı hiç döndürmeyen boş olarak belgelenirse, genellikle bir varsayılan olmadıkça ayarlayıcıya boş geçemeyeceğinizi belgelemem.

Bazı insanlar bu "belgeleri göz önünde bulundurma" eylemini belgelemeyi düşündükleri ancak gereksiz buldukları yerlere boş yorumlar ekleyerek işaretlemek isterler. Bu uygulamayı sevmiyorum, çünkü sadece kodu kaldırıyor ve yoluna giriyor.