137

ゲッターとセッターにコメントするためにどのような規則を使用しますか？これは私がかなり前から疑問に思っていたものです。たとえば、次のようになります。

/**
 * (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）の部分または（b）の部分のいずれかのみを入力してもよいかどうかだけが気になります。

どう思いますか？

4

14 に答える 14

186

絶対に無意味です-この種のがらくたがコードを乱雑にすることなく、あなたはより良いです：

/**
 * 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を設定する」とコメントで説明されているときはいつでも、誰かを絞め殺したいと思います。

于 2009-06-22T20:00:49.373 に答える
93

私は通常、セッターの場合はparam部分を、ゲッターの場合は@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の警告など）がきれいになり、重複がなくなります。

于 2009-06-22T19:31:21.243 に答える
38

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

答えが出ないように聞こえますが、説明が必要なことについては、時間を使ってコメントするようにしています。

于 2009-06-22T19:29:26.550 に答える
35

ゲッターとセッターに何らかの副作用がある場合、または初期化以外の何らかの前提条件が必要な場合（つまり、取得するとデータ構造からアイテムが削除される場合、または必要なものを設定するため）にのみ、ゲッターとセッターにコメントすることを心配します。 xとyを最初に配置します）。それ以外の場合、ここでのコメントはかなり冗長です。

編集：さらに、ゲッター/セッターに多くの副作用が関係していることがわかった場合は、ゲッター/セッターを別のメソッド名に変更することをお勧めします（つまり、スタックのプッシュとポップ）[ありがとうございます以下のコメント]

于 2009-06-22T19:31:26.843 に答える
13

コメントが（ブラウザから）JavaDocsとして表示されるときに、人々に何を見せたいかを自問してください。多くの人が、それは明らかなので、文書化は必要ないと言います。フィールドがプライベートの場合、これは当てはまりません（プライベートフィールドに対してJavaDocsを明示的にオンにしない限り）。

あなたの場合：

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

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

セッター/ゲッターを文書化するとき、私はエンコーディングから何を分離するのが好きです。例：

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

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

于 2009-06-22T19:42:30.797 に答える
8

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

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

public String getFoo() {
  return foo;
}

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

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

于 2011-04-16T00:23:05.373 に答える
6

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

私にとって、このメリットだけでもコストに見合う価値があります。

于 2014-02-11T02:04:25.483 に答える
5

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

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

呼び出されたメソッドがプロパティを設定するだけではないという困難な方法を見つけるのに不幸を感じたのは、私だけではないと確信していsetXます。

于 2009-06-22T19:39:54.487 に答える
3

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();
于 2011-10-15T23:28:03.223 に答える
1

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

一般に、コードは自立し、可能な限りコメントは避けてください。これにはリファクタリングが必要な場合があります。

編集：上記はゲッターとセッターのみを指します。些細なことではないものはすべて適切にjavadoc化する必要があると思います。

于 2009-06-22T19:30:25.517 に答える
1

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

あなたのコードを読んでいる誰かがそれperson.getFirstName()が人の名を返すことを理解できない場合、あなたは彼を解雇させるためにあなたの力ですべてを試すべきです。それがデータベースの魔法を実行し、いくつかのサイコロを投げ、名の秘書を呼び出して名を取得する場合、それは重要な操作であると想定し、それを適切に文書化するのが安全です。

一方、あなたperson.getFirstName()が人の名を返さない場合は...まあ、そこに行かないでくださいね。

于 2009-06-22T19:31:50.803 に答える
0

特にフィールド宣言にフィールドの内容を示すコメントを付ける場合は、（b）の部分に入力してもかまいません。

于 2009-06-22T19:28:20.750 に答える
0

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

于 2009-06-22T19:30:06.610 に答える
0

私はいつも両方を記入します。タイピングに費やされる追加の時間はごくわずかであり、一般に、情報が多いほど良いです。

于 2009-06-22T19:32:24.500 に答える