问题
你使用什么约定来评论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 赞)
一般没什么,如果我可以帮助它。吸气剂和制定者应该是不言自明的。
我知道这听起来像是一个非答案,但我试着用我的时间评论需要解释的事情。