简单的Getter / Setter评论

问题

你使用什么约定来评论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)部分即可。

你怎么看?


#1 热门回答(158 赞)

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

/**
 * 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()方法"设置了gobbledygook。",我想扼杀某人。


#2 热门回答(68 赞)

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


#3 热门回答(32 赞)

一般没什么,如果我可以帮助它。吸气剂和制定者应该是不言自明的。

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