简单的 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) 部分写更多，以提供上下文，但对于大多数 getters/setters 来说，措辞几乎完全相同。

我只是好奇，对于简单的 getters/setters，是否可以只填写 (a) 部分或 (b) 部分。

你怎么看？

原文由 ThaDon 发布，翻译遵循 CC BY-SA 4.0 许可协议

Answer 1

我通常只为 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 的警告）就会干净利落，并且没有重复。

原文由 sleske 发布，翻译遵循 CC BY-SA 3.0 许可协议

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() 方法“设置 gobbledygook”时，我想扼杀某人。

原文由 Michael Borgwardt 发布，翻译遵循 CC BY-SA 2.5 许可协议