Uygulamaya Javadoc yorumları eklenmeli mi?

Arayüze Javadoc yorumları eklemek ve uygulamaya Javadoc olmayan yorumlar eklemek doğru bir uygulama mı?

Çoğu IDE, yorumları otomatik olarak oluşturduğunuzda uygulamalar için JavaDoc olmayan yorumlar üretir. Somut yöntemin açıklaması olması gerekmez mi?

Yalnızca uygulama olan yöntemler için (geçersiz kılmalar değil), elbette, neden olmasın, özellikle de halka açıklarsa.

Eğer baskın bir durumunuz varsa ve herhangi bir metni kopyalayacaksanız, o zaman kesinlikle değil. Çoğaltma, tutarsızlıklara neden olmanın kesin bir yoludur. Sonuç olarak, kullanıcılar, yöntemi süper tipte mi yoksa alt tipte mi incelediklerine bağlı olarak yönteminiz hakkında farklı bir anlayışa sahip olacaklardır. @inheritDocBelge kullanın veya sağlamayın - IDE'ler, Javadoc görünümlerinde kullanmak için mevcut en düşük metni alacaktır.

Bir kenara, geçersiz kılan sürümünüz süper tipin belgelerine bir şeyler eklerse, başınız belada olabilir. Doktora programım sırasında bu problemi inceledim ve genel olarak insanların, bir süper tip aracılığıyla çağırıyorlarsa, geçersiz kılan versiyondaki ekstra bilgilerin asla farkında olmayacaklarını keşfettim.

Bu sorunu ele almak, geliştirdiğim prototip aracının en önemli özelliklerinden biriydi - Ne zaman bir yöntemi çağırsanız, hedefinin veya herhangi bir potansiyel geçersiz kılma hedefinin önemli bilgiler (örneğin, çelişen bir davranış) içerip içermediğine dair bir gösterge alırsınız. Örneğin, bir haritaya koymayı çağırırken, uygulamanız bir Ağaç Haritası ise, öğelerinizin karşılaştırılabilir olması gerektiği hatırlatıldı.

Hem uygulama hem de arayüz javadoc'a sahip olmalıdır. Bazı araçlarla, arabirimin belgelerini @inheritDoc anahtar sözcüğüyle devralabilirsiniz.

/**
 * @inheritDoc
 *
 * This implementation is very slow when b equals 3.
 */
public foo(int b)
{ ... }

Biraz iyi bir uygulama,

/**
 * {@inheritDoc}
 */

uygulamanın javadoc'u olarak (uygulamanın ayrıntıları hakkında açıklanacak fazladan bir şey yoksa).

Genel olarak, bir yöntemi geçersiz kıldığınızda, temel sınıfta / arayüzde tanımlanan sözleşmeye bağlı kalırsınız, böylece orijinal javadoc'u herhangi bir şekilde değiştirmek istemezsiniz. Bu nedenle, diğer cevaplarda bahsedilen @inheritDocveya @seeetiketinin kullanılması gerekli değildir ve aslında sadece kodda bir gürültü görevi görür. Tüm mantıklı araçlar, burada belirtildiği gibi süper sınıftan veya arayüzden javadoc yöntemini miras alır :

Inherit from classes and interfaces - Inheriting of comments occurs in all
three possible cases of inheritance from classes and interfaces:

- When a method in a class overrides a method in a superclass
- When a method in an interface overrides a method in a superinterface
- When a method in a class implements a method in an interface

Bazı araçların (sana bakıyorum, Eclipse!) Bir yöntemi geçersiz kılarken bunları varsayılan olarak oluşturması gerçeği, yalnızca üzücü bir durumdur, ancak kodunuzu gereksiz gürültülerle karıştırmayı haklı çıkarmaz.

Elbette, geçersiz kılma yöntemine bir yorum eklemek istediğinizde (genellikle bazı ek uygulama ayrıntıları veya sözleşmeyi biraz daha katı hale getirme) tam tersi bir durum olabilir. Ancak bu durumda, neredeyse hiç böyle bir şey yapmak istemezsiniz:

/**
 * {@inheritDoc}
 *
 * This implementation is very, very slow when b equals 3.
 */

Neden? Çünkü devralınan yorum muhtemelen çok uzun olabilir. Böyle bir durumda 3 uzun paragrafın sonunda fazladan cümleyi kim fark edecek? Bunun yerine, kendi yorumunuzun bir parçasını yazın, hepsi bu. Tüm javadoc araçları her zaman temel sınıf açıklamasını okumak için tıklayabileceğiniz bir tür Belirtilen bağlantı gösterir. Bunları karıştırmanın bir anlamı yok.

@see Arayüzdeki açıklamaya bir bağlantı oluşturur. Ancak uygulama ile ilgili bazı detaylar da eklemekte fayda var diye düşünüyorum.

Sjoerd, hem arayüzün hem de uygulamanın JavaDoc'a sahip olması gerektiğini doğru bir şekilde söylüyor. JavaDoc arayüzü yöntemin sözleşmesini tanımlamalıdır - yöntemin ne yapması gerektiği, hangi girdileri alması, hangi değerleri döndürmesi gerektiği ve hata durumunda ne yapması gerektiği.

Uygulama belgeleri, sözleşmedeki genişletmeleri veya kısıtlamaları ve ayrıca uygulamanın uygun ayrıntılarını, özellikle de performansı belirtmelidir.

Oluşturulan javadoc uğruna, evet önemli. Yalnızca arayüzü kullanarak somut bir uygulamaya referanslar bildirirseniz, arayüzün yöntemleri IDE tarafından alınacağından, bunu yapmaz.