Java'da eşittir gibi iyi anlaşılmış yöntemler için belge yazma

Eşittir, karşılaştırmak vb.

Aşağıdaki kodu göz önünde bulundurun.

 /**
 * This method compares the equality of the current object 
  with the object of same type
 */
@Override
public boolean equals(Object obj) {

               //code for equals

     }   

Şirketim yukarıdaki gibi yorum girmek için madalyalar. Yukarıdaki Javadoc yorumu gerekli mi? Eşit yöntemin ve beğenilerin (karşılaştırmak, karşılaştırmak) vb. Ne yaptığı açık ve iyi anlaşılmamış mı?

Önerileriniz neler?

JavaDoc , yorumların devralınmasını zaten destekliyor . Belgelere göre, "yapıcılar, alanlar ve iç içe sınıflar doktor yorumlarını miras almaz", ancak equals()irade gibi yöntemler . Yana Objectsınıf iyi belgelenmiş bulunmaktadır equals()yöntemi, sadece bir sorun olmadan bu belgelere tam devralmak için mümkün olmalıdır.

Yöntemin belgelerinin, IDE'nizde ve oluşturulan web belgelerinde erişilebilir olması için bir yerden gelmesi gerekir. Bir üst sınıfta bulunan doğru ve kapsamlı yorumları açıkça yeniden yazmak gerekli değildir ve kod dosyalarını kümelendirdiğini iddia ederim.

Bu şirket politikasıysa, iki seçeneğiniz vardır. Bununla birlikte rahatça gidebilir ve belgelerin yazılması ve korunması için ekstra çaba gösterebilirsiniz (genellikle belgelere ve kodlara da uygulanabilen KURU ilkesini ihlal eder). Diğer seçenek şirket politikasını aramak olacaktır - bu politikanın neden iyi bir fikir olmadığını ve onu değiştirmenin faydalarını açıklayın (zaman, para, çaba, kalite - yönetimin anladığı şeyler).

@inheritDocEkibimde ek açıklamayı genellikle için kullanıyoruz equals()ve hashcode()keşke yapmasaydık.

Bu iki yöntem için her zaman uygulamaya bakmalıyım. Bir yöntemi geçersiz kıldığınız için bu, farklı bir şey yapmasını istediğiniz anlamına gelir. Bence bu kendi belgelerini hak ediyor.

En azından yönteme hangi niteliklerin katıldığını ve hatta belki de neden olduğunu belgelemek iyidir.

Yorumların, doğru olan her tür geliştiriciye yardımcı olduğunu unutmayın.

Sorun, bazen eksik ve doğru olmamalarıdır.

Dürüst olmak gerekirse, 2 nesneyi karşılaştırmak zor olabilir (örneğin 2 fatura nesnesini karşılaştırmak), yönteminiz zamanla gelişebilir ve daha sonra yorumlanması gerekir.

Yöntemin amacını, kurallarını vb. "Yararlı ve anlamlı" bir yorumda göstermek iyi bir şeydir.

Aşağıdaki gibi boş yorumlarla kod yazmak çok kötü bir uygulamadır:

/**
 * This method compares the equality of the current object with the object of same type...
 */

Bu yararlı bir şey söylemiyor. Daha da kötüsü, hem stil hem de dilbilgisi açısından fakir:

1. Yorumlar asla "Bu yöntem" veya "Bu sınıf" veya "Bu" herhangi bir şeyle başlamamalıdır. Yorum, bir yöntem veya sınıfla kaynak dosyadaki konumuna göre ilişkilendirilir.

2. "nesne", "bir nesne" okumalıdır

3. "Eşitliği karşılaştırır" yalnızca bir nesnenin diğerinden daha fazla "eşitliğe" sahip olması durumunda mantıklıdır. Bu işlev "eşitlik" i karşılaştırmaz; birbirleriyle eşitliklerini belirlemek için nesneleri karşılaştırır.

Bunun yerine yorum, iki nesnenin ne zaman eşit kabul edildiğini göstermelidir. Burada, yöntem açıklamasını tamamen atlar ve yalnızca dönüş değerini belgelendiririm, örneğin:

public class Fraction {
  private int numerator, denominator;
  /**
   * @return true if <i>this</i> is numerically equal to <i>other</i>
   */
  public boolean equals(Fraction other) {
    return numerator * other.denominator == other.numerator * denominator;
  }
...
}

Önemsiz get / set yöntemleri için oluşturulan yorumlar en kötüsüdür.

Kodlama standardımız, bir yöntemi geçersiz kılarken, onu geçersiz kılmadan, üst sınıf veya arabirimdeki belgelerin alt veya uygulama sınıfı için artık doğru ve kapsamlı olmadığı sürece, belgenin belgelenmesinin gerekli olmadığını belirtir.

Eşittir için, karşılaştırmanın yalnızca veritabanı destekli bir varlık karşılaştırılırken birincil anahtarda yapıldığını, bunun için dokümanlarla tamamen tutarlı olmadığını belirtmek isteriz Object.equals().

Benim düşünceme göre, bence bu tartışmalı olabilir, yorumda sınıfı hangi sınıfı geçersiz kıldığınızı belirtmelisiniz. Sonra altı ay boyunca uygulandığını ya da uygulanmadığını merak ettiğinizde, sınıfı açmadan görebileceksiniz.

Bu yöntemlerin yaygın olduğunu ve geliştiricilerin çoğunun ne için olduğunu bildiğini bilerek IMO, oraya herhangi bir yorum koymanıza gerek kalmayacak. Yorumlar uzun vadede güvenilir değildir, çünkü bunlar uygulama güncellendiğinde güncellenmeyebilir ve karışıklığa neden olabilir. Bu nedenle, çoğunlukla güvenebileceğiniz şey olduğu için kodunuzu okunabilir yapmak her zaman daha iyidir.

Ayrıca, oluşturduğunuz / düzenlediğiniz kod ortak bir API için değilse, sadece dağınıklığı ve gürültüyü ekleyeceği için ortak yöntemler için javadocs'u dışarıda bırakabilirsiniz.