Simple Getter / Setter yorumları

Alıcıları ve ayarlayıcıları yorumlamak için hangi kuralı kullanıyorsunuz? Bu, bir süredir merak ettiğim bir şey, örneğin:

/**
 * (1a) what do you put here?
 * @param salary (1b) what do you put here?
 */
public void setSalary(float salary);

/*
 * (2a) what do you put here?
 * @return (2b)
 */
public float getSalary();

Her zaman 1a / b ve 2a / b için hemen hemen aynı şeyi yazdığımı görüyorum, 1a) Çalışanın maaşını, 1b) çalışanın maaşını belirler. Çok gereksiz görünüyor. Şimdi daha karmaşık bir şey görebiliyordum, bağlam sağlamak için (a) bölümlerine daha fazla yazabilirsiniz, ancak oradaki alıcıların / ayarlayıcıların çoğunluğu için ifade neredeyse tamamen aynıdır.

Merak ediyorum, basit alıcılar / ayarlayıcılar için sadece (a) bölümünü VEYA (b) bölümünü doldurmanın uygun olup olmadığını merak ediyorum.

Ne düşünüyorsun?

Genellikle ayarlayıcılar için param kısmını ve alıcılar için @return kısmını doldururum:

/**
 * 
 * @param salary salary to set (in cents)
 */
public void setSalary(float salary);

/**
 * @return current salary (in cents, may be imaginary for weird employees)
 */
public float getSalary();

Bu şekilde javadoc kontrol araçları (Eclipse'in uyarıları gibi) temiz çıkacak ve çoğaltma yapılmayacaktır.

Kesinlikle anlamsız - bu tür saçmalıklar kodunuzu karıştırmadan daha iyi durumda olursunuz:

/**
 * Sets the foo.
 * 
 * @param foo the foo to set
 */
public void setFoo(float foo);

Gerekirse çok yararlı:

/**
 * Foo is the adjustment factor used in the Bar-calculation. It has a default
 * value depending on the Baz type, but can be adjusted on a per-case base.
 * 
 * @param foo must be greater than 0 and not greater than MAX_FOO.
 */
public void setFoo(float foo);

Özellikle mülkün gerçekte ne anlama geldiğinin açıklaması, alan modellerinde çok önemli olabilir. Ne zaman yatırım bankacılarının, biyokimyacıların veya kuantum fizikçilerinin anladığı belirsiz isimlerle dolu bir fasulye gördüğümde ve yorumlar setGobbledygook () yönteminin "gobbledygook'u ayarladığını" açıkladığında, birini boğmak istiyorum.

Genelde hiçbir şey, eğer yardım edebilirsem. Toplayıcılar ve ayarlayıcılar kendi kendini açıklayıcı olmalıdır.

Bunun cevapsız gibi göründüğünü biliyorum, ancak zamanımı açıklama gerektiren şeyleri yorumlamak için kullanmaya çalışıyorum.

Alıcıları ve ayarlayıcıları yorumlamak için yalnızca bir tür yan etkiye sahiplerse veya başlatma dışında bir tür ön koşul gerektiriyorsa endişelenmenizi söyleyebilirim (yani: alma bir öğeyi bir veri yapısından kaldıracak veya ihtiyacınız olan bir şeyi ayarlamak için) önce x ve y'nin olması). Aksi takdirde buradaki yorumlar oldukça fazladır.

Düzenleme: Ek olarak, alıcı / ayarlayıcınızda çok sayıda yan etkinin bulunduğunu fark ederseniz, alıcı / ayarlayıcıyı farklı bir yöntem adına sahip olacak şekilde değiştirmek isteyebilirsiniz (yani: bir yığın için itme ve çıkarma) [için teşekkürler aşağıdaki yorumlar]

Kendinize, yorumlar JavaDocs olarak görüntülendiğinde (bir tarayıcıdan) insanların ne görmesini istediğinizi sorun. Birçok insan, açık olduğu için dokümantasyonun gerekli olmadığını söylüyor. Alan özelse bu geçerli olmaz (özel alanlar için JavaDocs'u açıkça etkinleştirmediğiniz sürece).

Senin durumunda:

public void setSalary(float s)
public float getSalary()

Maaşın ne ile ifade edildiği net değil. Sent, dolar, pound, RMB mi?

Ayarlayıcıları / alıcıları belgelerken, kodlamadan neyi ayırmayı seviyorum. Misal:

/**
 * Returns the height.
 * @return height in meters
 */
public double getHeight()

İlk satır yüksekliği döndürdüğünü söylüyor. Dönüş parametresi, yüksekliğin metre cinsinden olduğunu belgeler.

Alıcılardan ve ayarlayıcılardan alan değerini ve referansı yorumlamanıza izin vermek için neden sadece bir referans etiketi eklemiyorlar?

/**
* The adjustment factor for the bar calculation.
* @HasGetter
* @HasSetter
*/
private String foo;

public String getFoo() {
  return foo;
}

public void setFoo() {
  this foo = foo;
}

Böylece dokümantasyon alıcı ve ayarlayıcı için olduğu kadar alan için de geçerlidir (eğer özel javadoclar açıksa, yani).

Bu tür bir kazan plakası, Project Lombok kullanılarak önlenebilir . Sadece alan değişkenini belgeleyin, öyle olsa bileprivate ve Lombok açıklamalarının doğru şekilde belgelenmiş alıcılar ve ayarlayıcılar oluşturmasına izin verin.

Benim için bu fayda tek başına maliyete değer .

Temelde kapsamlı belgelemenin zaman kaybı olduğunu söyleyen cevaplar beni gerçekten hayal kırıklığına uğrattı. Nasıl API müşterileri adında bir yöntem olduğunu bilmek gerekiyor setXbir olan standart JavaBean özellik kurucu sürece sen belgelerinde kadar net söylemek ?

Dokümantasyon olmadan, arayan kişinin, yöntemin herhangi bir yan etkisi varsa, takip edilen görünen kongre hakkında parmaklarını şaklatmak dışında hiçbir fikri olmayacaktır.

Eminim ki, adı verilen bir yöntemin setXbir özellik belirlemekten çok daha fazlasını yapmasının zor yolunu bulmak için talihsizlik yaşayan tek kişi ben değilim .

Alıcı / ayarlayıcıda özel bir işlem yoksa genellikle yazarım:

Javadoc ile (özel seçenekle):

/** Set {@see #salary}. @param {@link #salary}. */
public void setSalary(float salary);

ve / veya

/** 
 * Get {@see #salary}.
 * @return {@link #salary}.
 */
public float salary();

Doxygen ile (özel ekstrakt seçeneğiyle):

/** @param[in] #salary. */
public void setSalary(float salary);

/** @return #salary. */
public float salary();

Erişimcileri yorumlamak, özellikle de herhangi bir yerde herhangi bir işlem yapmazlarsa, gereksizdir ve parmak uçlarını israf eder.

Kodunuzu okuyan biri bunu anlayamazsa person.getFirstName() , bir kişinin ilk adını döndürdüğünü onu kovmak için gücünüzdeki her şeyi denemelisiniz. Bir veritabanı büyüsü yaparsa, birkaç zar atarsa, ilk adı almak için İlk İsimler Sekreterini çağırırsa, bunun önemsiz bir işlem olmadığını varsaymak ve iyi belgelemek güvenlidir.

Öte yandan, person.getFirstName()bir kişinin adını iade etmezseniz ... peki, oraya gitmeyelim, olur mu?

Alan adı içeriği yeterince açıklayıcıysa hiçbir şey koymayın.

Genel olarak, kodun kendi başına durmasına izin verin ve mümkünse yorum yapmaktan kaçının. Bu, yeniden düzenleme gerektirebilir.

DÜZENLEME: Yukarıdakiler yalnızca alıcılara ve ayarlayıcılara atıfta bulunur. Önemsiz olmayan herhangi bir şeyin düzgün bir şekilde javadoc'lanması gerektiğine inanıyorum.

(b) bölümünü doldurmanızda bir sakınca yoktur, özellikle alan bildirimine alanın neyle ilgili olduğunu belirten bir yorum koyarsanız.

Javadoc hiçbir şey eklemezse, javadoc'u silerim ve otomatik olarak oluşturulan yorumları kullanırım.

Ben her zaman ikisini de doldururum. Yazmak için harcanan ek süre önemsizdir ve genel olarak daha fazla bilgi, daha azdan daha iyidir.