简单的 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);

尤其是对属性实际含义的解释在领域模型中可能至关重要。每当我看到一个 bean 的属性名称晦涩难懂，只有投资银行家、生物化学家或量子物理学家才能理解，并且 cmets 解释说 setGobbledygook() 方法“设置了 gobbledygook”。我想掐死某人。

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

一般没什么，如果我能帮忙的话。 getter 和 setter 应该是不言自明的。

我知道这听起来像是一个无法回答的问题，但我会尽量利用我的时间来评论需要解释的事情。

Answer 4

我想说，如果 getter 和 setter 有某种副作用，或者需要初始化之外的某种先决条件（即：getter 将从数据结构中删除一个项目，或者为了设置你需要先有 x 和 y 的东西）。否则这里的 cmets 就相当多余了。

编辑：此外，如果您确实发现 getter/setter 涉及很多副作用，您可能希望更改 getter/setter 以具有不同的方法名称（即：堆栈的 push 和 pop） [感谢下面的cmets]

Answer 5

问问自己，当 cmets 被视为 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。

对我来说，仅此一项好处就值得costs。

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

如果字段名称足以描述内容，则不要输入任何内容。

一般来说，让代码独立存在，并尽可能避免注释。这可能需要重构。

编辑：以上仅指 getter 和 setter。我相信任何不平凡的事情都应该被正确地 javadoc'ed。

Answer 12

可以填写 (b) 部分，特别是如果您在字段声明中添加注释，说明该字段的全部内容。

Answer 13

如果 javadoc 没有添加任何内容，我会删除 javadoc 并使用自动生成的 cmets。

Answer 14

我总是填写两个。打字所花费的额外时间可以忽略不计，一般来说，更多信息总比更少信息要好。