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

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

/**
 * (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）部分のいずれかのみを入力してもよいかどうか、私は興味があります。

どう思いますか？

私は通常、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の警告など）がクリーンになり、重複がなくなります。

絶対に無意味です-このようながらくたがコードを散らかさない限り、あなたのほうが良いでしょう：

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

私がそれを助けることができるなら、一般的に何もない。ゲッターとセッターは一目瞭然です。

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

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

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

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

あなたの場合：

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

給与が何で表されているのかはっきりしていません。それは、セント、ドル、ポンド、人民元ですか？

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

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

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

フィールドの値とゲッターとセッターからの参照にコメントを付けるための参照タグを含めないのはなぜですか。

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

public String getFoo() {
  return foo;
}

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

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

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

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

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

ドキュメンテーションがなければ、呼び出し側は、メソッドに何らかの副作用があるかどうか、どのような規則に従っているのかを理解する以外に、まったくわかりません。

ここで呼び出されたメソッドsetXがプロパティを設定するだけではなく、はるかに多くのことを実行する困難な方法を見つけたのは、私だけが不幸なことではないでしょう。

ゲッター/セッターに特別な操作がない場合、通常は次のように記述します。

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

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

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

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

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

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

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

特にフィールドの内容を示すコメントをフィールド宣言に配置する場合は、（b）の部分に入力しても問題ありません。

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

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