简单的getter / setter评论(Simple Getter/Setter comments

你用什么约定评论getter和setter方法？ 这是我一直想知道，很长一段时间，例如：

/**
 * (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）的雇员的薪水。 它只是似乎很是多余的。 现在我能看到更复杂的东西，你可能会写更多的（一）部分，给予语境，但对于大多数的getter / setter方法在那里的措辞几乎是完全一样的。

我只是好奇，如果，对于简单的getter / setter方法的确定，只是无论是在部分（a）或（b）部分填写。

你怎么看？

Answer 1:

我通常只是填补制定者帕拉姆部分，并为干将的@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的警告）会出来干净，而且也没有重复。

Answer 2:

绝对没有意义的 - 你最好没有这种垃圾塞满你的代码：

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

什么样的属性实际上意味着可以在域模型至关重要特别的解释。 每当我看到豆满属性与模糊的名字，只有投资银行家，生物化学或量子物理学家理解和注释解释说，setGobbledygook（）方法“设置官样文章”，我想掐死的人。

Answer 3:

一般来说没什么，如果我能帮助它。 getter和setter方法应该是不言自明的。

我知道这听起来像一个非答案，但我尝试使用我的时间评论事情需要解释。

Answer 4:

我看大概评论getter和setter唯一担心的，如果他们有某种副作用，或者需要某种前提条件的初始化之外（即：将获得从数据结构中删除的项目，或以设置你需要的东西有一个适当的X和Y在前）。 否则，这里的评论是相当多余。

编辑：另外，如果你发现有很多的副作用参与您的getter / setter，你可能要改变的getter / setter有不同的方法名称（即：push和pop的堆栈）[感谢下面的评论]

Answer 5:

问问自己，你希望人们能看到当评论被视为JavaDoc中（从浏览器）什么事。 很多人说，文件是没有必要的，因为很明显。 如果字段是私有的，这将不成立（除非你明确地打开JavaDoc中的私有字段）。

你的情况：

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

在表达什么工资目前尚不清楚，这是美分，美元，英镑，人民币？

当记录制定者/吸气，我想从编码什么分开。 例：

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

第一行表示，它返回的高度。 返回参数文档身高以米为单位。

Answer 6:

为什么他们不只是包括参考标签，让你评论的字段值和getter和setter参考。

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

public String getFoo() {
  return foo;
}

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

因此，该文件适用于getter和setter，以及该领域（如私人的javadoc开启时即是）。

Answer 7:

这种样板可以通过使用可避免项目龙目岛 。 只是记录字段变量，即使是private ，让龙目岛标注生成适当的记录getter和setter。

对我来说，这个好处是值得的成本 。

Answer 8:

我真的很失望基本上说全面的文档化是浪费时间的答案。 您的API的客户应该如何知道一个调用的方法setX是一个标准的JavaBean的属性设置 ，除非你的文档中说的那么清楚 ？

没有证件，呼叫者就没有任何想法如果方法有任何副作用，比通过他们对视公约手指等被人跟踪。

我敢肯定，我不是唯一一个在这里有过不幸找出硬盘的方式，一种叫做方法setX并不仅仅是设置一个属性更一大堆。

Answer 9:

如果没有特殊操作的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();

Answer 10:

在谈到访问器，特别是如果他们不做任何操作的任何地方，是不必要的，指尖的浪费。

如果有人读你的代码不能明白person.getFirstName()返回一个人的名字，你应该尝试在你的一切权力，让他解雇。 如果是这样一些数据库的魔法，抛出了几个色子，呼叫首先姓名的秘书拿到的第一个名字，它是安全的假设这是一个不平凡的操作，并顺利将其记录下来。

如果，另一方面，你person.getFirstName()不返回一个人的名字......好了，让我们不要去那里，好吗？

Answer 11:

如果字段名称是suficiently描述的内容，不要把任何东西。

一般情况下，让代码自我站立，并避免发表评论，如果在所有可能的。 这可能需要重构。

编辑：以上是指只有getter和setter。 我相信任何事情不平凡应适当javadoc'ed。

Answer 12:

它是确定填写（b）部分，特别是如果你把一个评论，在指示场是所有关于字段声明。

Answer 13:

如果javadoc中不添加任何东西，我删除Javadoc和使用自动生成的注释。

Answer 14:

我总是填写两者。 额外花费的时间打字是微不足道的，而更多的信息比少好，一般。

Answer 15:

如果它是一个getter / setter方法，应当记录在案。

我离题了这里，但如果能够取得一个属性，也许这是类的用户更简单的编码更好。 我进一步离题，但对于所有那些在他们的任何地方的“java”的意见，谁说，这是java吗？ （标签，但这个问题可以在任何位置应用真的）

文章来源: Simple Getter/Setter comments