Bir yöntemin imzasında HER parametre için bir javadoc yorumu yazmak gerekli midir?

Ekibimdeki geliştiricilerden biri, bir yöntemin imzasında HER parametre için bir javadoc yorumu yazmanın gerekli olduğuna inanıyor. Bunun gerekli olduğunu düşünmüyorum ve aslında zararlı bile olabileceğini düşünüyorum.

Öncelikle, parametre adlarının açıklayıcı ve kendi kendini belgelemesi gerektiğini düşünüyorum. Parametrelerinizin ne için olduğu hemen belli değilse, muhtemelen Yanlış Yapıyorsunuzdur. Ancak, bazen bir parametrenin ne için belirsiz olduğunu anlıyorum, bu nedenle, evet, parametreyi açıklayan bir javadoc yorumu yazmalısınız.

Ama bunu HER parametre için yapmanın gereksiz olduğunu düşünüyorum. Parametrenin ne için olduğu zaten açıksa, javadoc yorumu gereksizdir; sadece kendiniz için ekstra işler yaratıyorsunuz. Ayrıca, kodunuzu korumak zorunda olan herkes için ekstra iş oluşturuyorsunuz. Yöntemler zamanla değişir ve yorumları korumak, kodunuzu korumak kadar önemlidir. Kaç kez "yorumun Z nedeni için X var" gibi bir yorum gördünüz ve yorumun güncel olmadığını ve aslında yöntem artık X parametresini bile almadığını görüyor musunuz? Her zaman olur, çünkü insanlar yorumları güncellemeyi unutur. Yanıltıcı bir yorumun hiçbir yorumdan daha zararlı olduğunu iddia ediyorum. Ve böylece aşırı yorum yapma tehlikesi vardır: gereksiz belgeler oluşturarak,

Ancak, ekibimdeki diğer geliştiriciye saygı duyuyorum ve belki de haklı olduğunu ve yanıldığımı kabul ediyorum. Bu yüzden sorumu size getirdim, geliştiriciler: Gerçekten HER parametre için bir javadoc yorumu yazmak gerekli mi? Burada kodun şirketime ait olduğunu ve herhangi bir dış taraf tarafından kullanılmayacağını varsayalım.

Javadoc (ve Microsoft kelimesinde XMLDoc) ek açıklamaları yorum değildir , belgelerdir .

Yorumlar olmasını istediğiniz kadar seyrek olabilir; kodunuzun yarıya kadar okunabilir olduğunu varsayarsak, sıradan yorumlar yalnızca gelecekteki geliştiricilere zaten iki saat boyunca baktıkları kodu anlama / koruma konusunda yardımcı olmak için işaret levhalarıdır.

Dokümantasyon bir temsil sözleşme kodu ve onun arayanların bir birlik arasında. Herkese açık API'nın bir parçasıdır. Her zaman olduğu Javadoc / XMLdoc bir yardım dosyasında veya bir otomatik tamamlama / Intellisense / kod tamamlama açılır pencerede ya sona erecek ve insanlar tarafından gözlemlenebilir farz değil kodunuzun iç elemanların inceleyerek ama sadece isteyen kullanmak bazı amaçla onların kendi.

Bağımsız değişken / parametre adları hiçbir zaman açıklayıcı değildir. Her zaman geçmiş günü kod üzerinde çalışarak geçirdiğinizi düşünürsünüz , ancak 2 haftalık bir tatilden sonra tekrar gelmeyi deneyin ve gerçekten ne kadar yararsız olduklarını göreceksiniz.

Beni yanlış anlamayın - değişkenler ve argümanlar için anlamlı isimler seçmek önemlidir. Ancak bu bir kodla ilgilidir, bir dokümantasyonla ilgili değildir. "Kendini belgeleme" ifadesini çok fazla anlamayın; harici dokümantasyon (sözleşmeler) değil , dahili dokümantasyon (yorumlar) bağlamında kastedilmektedir .

Ya her şeyi yorumlayın ya da hiçbir şey yorumlamayın (açıkçası her şeyi yorumlamak çok daha iyi bir seçimdir). Kodunuzu kullanan birini düşünün, API'nizi doğrudan kaynak dosyanızda veya oluşturulan bir doc dosyasında (ör. Oksijen çıkışı) gözden geçirin. Tutarsızlıklar genellikle karışıklığa yol açar, bu da neden bir şeyin neden yorumlanmadığını anlamak için kaynaktan kazarak harcanan zamana yol açar, bu da parametre ilk etapta yorumlanmış olsaydı kaçınılması gereken zaman kaybına yol açar.

Unutmayın: Sizin için mantıklı olan bir şey, ne kadar sıradan olduğunuzu düşünürseniz düşünün, başka biri tarafından tamamen farklı bir şekilde yorumlanabilir (İngilizce okuma ve kodunuzu anlamaya çalışan biri kadar düşünün).

Tüm bunları söyledikten sonra, diğer geliştirici her şeyi belgelemenin önemini vurguluyorsa , belgelerin güncel tutulmasına da (daha fazla değilse) vurgu yapılması gerekir. Belirttiğiniz gibi, eski yorumlara sahip olmaktan çok daha kötü değildir (atlanan dokümanlardan daha kötü değilse de kötüdür).

Geliştirici döngülerinin korumaya çalıştığımız kaynak olduğu varsayımından başlayalım.

Bu, devs'nin kendi kendine belirgin parametreleri ve dönüş değerlerini belgelemek için zaman kaybetmemesi gerektiği anlamına gelir, değil mi?

Hadi yıkalım.

Marjinal yorumların gerçekten önemsiz olduğunu ve hiçbir düşünce veya araştırma gerektirmediğini varsayarak, her şeyi belgelersek, bu yorumu gerçekten yazmak ve yazım hatalarını düzeltmek için eklenen zamandır.

Seçip seçersek, maliyetler şunlardır:

• Ekibinizdeki her şeyin belgelenmesi gerektiğini düşünen diğer geliştiricilerle tartışmayı kazanmak ve kazanmak.
• Her parametre için, bunun belgelenmesi gerekip gerekmediğinin belirlenmesi.
• Birisinin bir parametrenin belgelenmesi gerekip gerekmediği konusunda farklı bir görüşü olduğunda ekibinizle daha fazla tartışma
• Kendini açıklayan bir parametrenin böyle olmadığı ortaya çıktığında, kodu avlamak ve araştırmak için zaman harcayın.

Yani, her şeyi belgelemeye meyilli olurum. Olumsuz kesin, ancak bulunur.

Yine de Javadoc yazıyorsanız, "bariz" parametreleri de dahil olmak üzere tamamen yazabilirsiniz. Size veya diğer geliştiriciye açık olabilirler, ancak ona bakan yeni herkes her parametrenin amacını bilmekten fayda sağlayacaktır.

Javadoc'u düzgün bir şekilde korumak için, gelişiminiz için bu konuda size yardımcı olacak araçları kullanmanız gerekir. Tutulma akla geliyor. Tabii ki, önemliyse, ekipteki herkesin, yorumlar da dahil olmak üzere kodu korumak için üzerlerine düşeni yapmasını sağlamalısınız.

Javadoc'un koddan ayrıyken görünür hale getirilebileceğini unutmayın, ana örnek Java API'sıdır . Javadoc'u bir yönteme her parametre için dahil etmediğinizde, yöntemi ve nasıl kullanılabileceğini yanlış temsil edersiniz.

'gerekli' tamamen özneldir. Ben 'senin durumunda, ne soruyorsun olduğunu düşünüyorum gerekir Eğer bir Javadoc yorum eklemek'. Uygulamanızın kapsamını veya içeriğini bilmeden, sizin için neyin uygun olduğunu nasıl bileceğiz?

Bu halka açık kod (yani, api gibi başkalarının erişmesi gerekiyorsa) evetse, her parametreyi belgeleyin. Okuyucunun projeyi sizin kadar bildiğini varsaymayın. Ama aksi takdirde, kendi kararlarınızı vermek size ve ekibinize bağlıdır.