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

StackOverflow https://stackoverflow.com/questions/1028967

質問

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

/**
 * (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 を使用することで回避できます。フィールド変数を private であっても文書化し、Lombokアノテーションが適切に文書化されたゲッターとセッターを生成できるようにします。

私にとっては、この利点だけでも費用の価値があります。

>

基本的な包括的な文書化は時間の無駄であると基本的に答えていることに失望しています。 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（）が人の名を返さない場合...まあ、そこに行かないようにしましょうか？

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

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

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

（b）部分に記入しても構いません。特にフィールド宣言にコメントを入れて、フィールドが何であるかを示している場合は特にそうです。

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

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

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

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

ライセンス： CC-BY-SA と 帰属
所属していません StackOverflow
scroll top