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

我通常只填充 setters 的 param 部分，以及 getters 的 @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 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);

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

Answer 3

我总是两者都填写。 花费在打字上的额外时间可以忽略不计，而且一般来说，更多的信息总比更少的信息好。

Answer 4

如果 javadoc 未添加任何内容，我将删除 javadoc 并使用自动生成的注释。

Answer 5

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

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

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

Answer 6

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

Answer 7

如果 getter/setter 中没有特殊操作，我通常会写：

With Javadoc (with private option):

/** Set {@see #salary}. @param {@link #salary}. */
public void setSalary(float salary);

和/或

/** 
 * Get {@see #salary}.
 * @return {@link #salary}.
 */
public float salary();

With Doxygen (with private extract option):

/** @param[in] #salary. */
public void setSalary(float salary);

/** @return #salary. */
public float salary();

Answer 8

注释访问器，特别是如果它们不在任何地方执行任何操作，是不必要的，而且浪费指尖。

如果阅读您代码的人无法理解 person.getFirstName() 返回某人的名字，您应该尽一切努力让他被解雇。 如果它执行了一些数据库魔法，扔了几个骰子，调用名字秘书来获取名字，就可以安全地假设这是一个不平凡的操作，并很好地记录它。

另一方面，如果您的 person.getFirstName() 没有返回一个人的名字...那么，我们不要去那里，好吗？

Answer 9

问问自己，当评论被视为 JavaDoc（从浏览器）时，您希望人们看到什么。 许多人说文档是不必要的，因为它是显而易见的。 如果字段是私有的（除非您明确地为私有字段打开 JavaDocs），则这将不成立。

就您而言：

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

不清楚工资用什么表示。是美分、美元、英镑、人民币吗？

在记录 setter/getters 时，我喜欢将内容与编码分开。 示例：

/**
 * Returns the height.
 * @return height in meters
 */
public double getHeight()

第一行表示返回高度。 返回参数记录高度以米为单位。

Answer 10

为什么他们不只包含一个引用标签来让您评论字段值以及 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 11

使用 Project Lombok 可以避免这种样板文件。 只需记录字段变量，即使它是私有的，然后让 Lombok 注释生成正确记录的 getter 和 setter。

对我来说，仅这个好处就值得成本。

Answer 12

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

如果没有文档，调用者将不知道该方法是否有任何副作用，除了祈祷所遵循的明显约定之外。

我确信我不是唯一一个不幸地发现名为 setX 的方法不仅仅只是设置属性的方法的人。

Answer 13

我想说，只担心注释 getter 和 setter 如果它们有某种副作用，或者需要初始化之外的某种前提条件（即：获取将从数据结构中删除一个项目，或者为了设置您需要的东西）首先让 x 和 y 就位）。 否则这里的评论是相当多余的。

编辑：此外，如果您确实发现 getter/setter 涉及很多副作用，您可能需要更改 getter/setter 以具有不同的方法名称（即：堆栈的推送和弹出）[感谢下面的评论]

Answer 14

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

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