web-dev-qa-db-ja.com

シンプルなゲッター/セッターコメント

ゲッターとセッターをコメントするためにどのような規則を使用していますか?これは私がかなり長い間不思議に思っていたものです、例えば:

/**
 * (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();

私は常に、1a/bと2a/bについてまったく同じことを書いていることに気付きます。1a)従業員の給与を設定し、1b)従業員の給与を設定します。とても冗長なようです。今、私は、コンテキストを与えるために(a)の部分にさらに書くかもしれないより複雑な何かを見ることができましたが、そこにあるゲッター/セッターの大部分については、文言はほとんどまったく同じです。

単純なゲッター/セッターについては、(a)部分OR(b)部分のいずれかのみを埋めてもよいかどうかだけに興味があります。

どう思いますか?

118
ThaDon

通常、setterの場合はparam部分を、getterの場合は@return部分を埋めます。

/**
 * 
 * @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();

そうすれば、javadocチェックツール(Eclipseの警告など)がきれいになり、重複はなくなります。

79
sleske

まったく意味がありません-この種のがらくたはコードを乱雑にしない方が良いでしょう:

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

保証されている場合、非常に便利です:

/**
 * 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);

特に、プロパティが実際に何を意味するのかの説明は、ドメインモデルでは非常に重要です。投資銀行家、生化学者、または量子物理学者だけが理解できる曖昧な名前のプロパティでいっぱいのBeanを見るたびに、コメントはsetGobbledygook()メソッドが「gobbledygookを設定する」と説明します。

167

私がそれを助けることができれば、一般的には何もありません。ゲッターとセッターは自明であるべきです。

私はそれが無回答のように聞こえるかもしれませんが、説明を必要とするものにコメントするために自分の時間を使っています。

36
Eric Wendelin

ゲッターとセッターに何らかの副作用がある場合、または初期化以外の何らかの前提条件が必要な場合(つまり、取得によってデータ構造から項目が削除されるか、必要なものを設定する場合)最初にxとyを配置する)。それ以外の場合、ここのコメントはかなり冗長です。

編集:さらに、ゲッター/セッターに多くの副作用が関与していることがわかった場合、ゲッター/セッターを変更して別のメソッド名(スタックのプッシュアンドポップ)を変更することもできます[ありがとうございます以下のコメント]

34
Gopherkhan

コメントが(ブラウザから)JavaDocsとして表示されたときに、人々に何を見せてほしいか自問してください。多くの人は、ドキュメントは明らかであるため、必要ではないと言っています。これは、フィールドがプライベートの場合は保持されません(プライベートフィールドに対してJavaDocsを明示的にオンにしない限り)。

あなたの場合:

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

給与が何で表されるかは明確ではありません。それはセント、ドル、ポンド、人民元ですか。

セッター/ゲッターをドキュメント化するとき、エンコーディングから何を分離するのが好きです。例:

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

最初の行は、高さを返すことを示しています。戻りパラメーターは、高さがメートル単位であることを文書化します。

12
Steve Kuo

フィールド値とゲッターとセッターからの参照にコメントできるように、参照タグを含めるだけではどうでしょうか。

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

public String getFoo() {
  return foo;
}

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

そのため、ドキュメンテーションはフィールドだけでなくゲッターとセッターにも適用されます(プライベートjavadocsがオンになっている場合)。

9
Steve

Project Lombok を使用すると、この種の定型文を回避できます。 privateであってもフィールド変数を文書化し、Lombokアノテーションに適切に文書化されたゲッターとセッターを生成させます。

私にとっては、このメリットだけでも コスト に値します。

6
Michael Scheper

基本的に包括的な文書化は時間の無駄だと基本的に言っている答えに本当に失望しています。 APIのクライアントは、setXというメソッドが標準JavaBeanプロパティセッターであることをどのように認識しているのでしょうかドキュメントに

ドキュメントがなければ、呼び出し元は、見かけの慣習について指を交差させる以外に、メソッドに何らかの副作用があるかどうかはまったくわかりません。

setXと呼ばれるメソッドがプロパティを設定するだけではなく、それ以上のことを行うという困難な方法を見つけ出す不幸を経験したのは、私だけではないでしょう。

4
oxbow_lakes

Getter/setterに特別な操作がない場合は、通常次のように記述します。

Javadocを使用(プライベートオプションを使用):

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

および/または

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

Doxygenを使用(プライベート抽出オプションを使用):

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

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

フィールド名が内容を十分に説明している場合は、何も入れないでください。

一般的に、コードは独立したものにし、可能な限りコメントを避けます。これにはリファクタリングが必要な場合があります。

編集:上記はゲッターとセッターのみを参照しています。些細でないものはすべて適切にjavadocされるべきだと思います。

特にどこでも操作を行わない場合、アクセサーにコメントを付けることは不要であり、指先の無駄です。

コードを読んでいる人がperson.getFirstName()が人の名を返すことを理解できない場合は、力を尽くして彼を解雇する必要があります。データベースに何らかの魔法をかけ、いくつかのサイコロを投げ、名の秘書を呼び出して名を取得します。それは簡単な操作ではないと想定し、それを適切に文書化します。

一方で、あなたのperson.getFirstName()が人の名を返さない場合...まあ、そこに行かないようにしましょうか?

1
Henrik Paul

(b)部分を埋めても構いません。特に、フィールド宣言にフィールドの内容を示すコメントを入力する場合はそうです。

0
akf

Javadocが何も追加しない場合、javadocを削除し、自動生成されたコメントを使用します。

0
Alex B

私は常に両方に記入します。一般に、タイピングに費やす追加時間はごくわずかであり、より多くの情報が少ないよりも優れています。

0
Paul Sonier

ゲッター/セッターの場合は、文書化する必要があります。

ここでは脱線しますが、プロパティにできる場合は、おそらくクラスのユーザーのコーディングを単純化するのに適しています。私はさらに脱線しますが、「Java」が含まれているすべてのコメントについては、誰がそれがJavaだと言ったのですか? (タグですが、質問は実際にどこでも適用できます)

0