简单的Getter/Setter评论

Question

您使用什么约定来评论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)雇员的工资.这似乎是多余的.现在我可以看到更复杂的东西,你可以在(a)部分写更多内容,给出上下文,但对于大多数的getter/setter,那里的措辞几乎完全相同.

我只是好奇,如果对于简单的getter/setter,只需填写(a)部分或(b)部分即可.

你怎么看？

Answer 1

绝对毫无意义 - 如果没有这种垃圾使你的代码混乱,你会变得更好:

/**
 * 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 2

我通常只为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的警告)将会变得干净,并且没有重复.

Answer 3

一般没什么,如果我可以帮助它.吸气剂和二传手应该是不言自明的.

我知道这听起来像是一个非答案,但我试着用我的时间来评论需要解释的事情.

Answer 4

我只是说如果他们有某种副作用,或者在初始化之外需要某种先决条件(例如:获取将从数据结构中删除项目,或者为了设置你需要的东西),只会担心评论getter和setter首先让x和y到位).否则这里的评论非常多余.

编辑:此外,如果你确实发现你的getter/setter中涉及很多副作用,你可能想要更改getter/setter以使用不同的方法名称(即:push和pop for a stack)[感谢以下评论]

Answer 5

问问自己,当评论被视为JavaDocs时,您希望人们看到什么(来自浏览器).许多人说文档没有必要,因为它很明显.如果字段是私有的,则不会成立(除非您为私有字段明确打开JavaDocs).

在你的情况下:

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

目前尚不清楚薪水表示的是什么.它是美分,美元,英镑,人民币？

在记录setter/getter时,我喜欢将其与编码分开.例:

/**
 * 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以及字段(如果启用私有javadocs).

Answer 7

使用Project Lombok可以避免这种样板.只记录字段变量,即使它是private,并让Lombok注释生成正确记录的getter和setter.

对我来说,这个好处是值得的成本.

Answer 8

我对基本上说全面记录是浪费时间的答案感到非常失望。除非您在文档中明确说明，否则您的 API 的客户如何知道被调用的方法setX是标准的 JavaBean 属性设置器？

如果没有文档，调用者将不知道该方法是否有任何副作用，除了对所遵循的明显约定交叉手指。

我敢肯定，我不是这里唯一不幸地发现被调用的方法setX所做的不仅仅是设置属性的困难方式。