Java 简单的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）部分

---

你怎么看？

填写（b）部分是可以的，特别是如果你在字段声明中添加了一条注释，说明字段的全部内容。

如果我能帮忙的话，通常什么都没有。能手和二传手应该不言自明

---

我知道这听起来好像没有答案，但我试着用我的时间来评论需要解释的事情。

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

如果字段名对内容有足够的描述，就不要放任何内容

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

---

编辑：以上仅指getter和setter。我相信任何非琐碎的东西都应该正确地javadoc。

我通常只为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的警告）将变得干净，并且不会出现重复。

我想说的是，如果getter和setter有某种副作用，或者需要初始化之外的某种先决条件，只需要对它们进行注释（即：getting将从数据结构中删除一个项，或者为了设置某个项，您需要先将x和y放在适当的位置）。否则，这里的注释是多余的

---

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

注释访问者，特别是如果他们在任何地方都不做任何操作，是不必要的，也是对指尖的浪费

如果有人阅读您的代码时无法理解

person.getFirstName（）

返回一个人的名字，你应该尽你所能让他被解雇。如果它做了一些数据库魔术，掷了几个骰子，打电话给名字秘书以获得名字，那么可以安全地假设这是一个不平凡的操作，并做好记录

---

另一方面，如果您的

person.getFirstName（）

不会返回一个人的名字……好吧，我们不要去那里，好吗？

我总是两个都填。额外的打字时间可以忽略不计，总的来说，信息多总比信息少好。

我对答案很失望，基本上说全面的文档编制是浪费时间。你的客户怎么样r API应该知道名为

setX

的方法是标准的JavaBean属性设置器，除非您在文档中明确说明了这一点

如果没有文档记录，调用者将完全不知道该方法是否有任何副作用，除了交叉手指表示遵循明显的约定

---

我相信我不是这里唯一一个不幸发现一个叫做

setX

的方法不仅仅是设置一个属性的方法的人。

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

就你而言：

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

不清楚工资是用什么表示的，是美分、美元、英镑还是人民币

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

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

---

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

绝对没有意义-如果代码中没有这种垃圾，你会更好：

/**
 * 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”，我想掐死某人。

为什么它们不包括一个引用标记，让您对字段值以及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以及字段（如果private javadocs已打开）。

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

使用Javadoc（使用私有选项）：

和/或

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

使用Doxygen（使用专用提取选项）：

---

使用可以避免这种样板文件。只需记录字段变量，即使它是

私有的

，并让Lombok注释生成正确记录的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;
}

---

对我来说，这一好处本身就是值得的。

只有当你说“这是一个属性设置者”时，它们才是不言自明的。否则，API的客户根本不知道方法内部到底发生了什么。谁说了一些不言自明的话？可以说，您应该将具有副作用的getter的名称更改得更清楚，因为并非所有开发人员都会阅读注释。这很好-但这要求API的用户知道这一点，对吗如果有任何副作用，它们都会被记录下来的！akf，我在发帖后想：）I gues

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

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