简单的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）部分中编写更多内容，以提供具体背景信息，但是对于大多数使用方法的人来说，措辞几乎完全相同。

我只是好奇，对于简单的获取者/设置者而言，仅填写（a）部分还是（b）部分是否可以。

你怎么看？

我通常只为setter填充参数部分，为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的警告）将变得干净利落，并且没有重复。

绝对没有意义-如果没有这种垃圾使您的代码混乱，您会更好：

/**
 * 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”时，我就想勒死一个人。

如果我能帮助的话，通常没有任何帮助。吸气剂和吸气剂应该是不言自明的。

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

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

编辑：此外，如果您确实发现吸气剂/设置器涉及很多副作用，则可能需要更改吸气剂/设置器以使用不同的方法名称（即：推入并弹出堆栈）。下面的评论]

问自己，当注释被JavaDocs（从浏览器）查看时，您希望人们看到什么。许多人说文档是不必要的，因为它很明显。如果该字段是私有字段，则此设置将不成立（除非您显式打开私有字段的JavaDocs）。

在您的情况下：

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

目前尚不清楚用什么工资表示。是美分，美元，英镑，人民币？

在记录设置器/获取器时，我喜欢将内容与编码分开。例：

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

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

为什么不只包含参考标记，以便您注释字段值以及来自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的话）。

使用Project Lombok可以避免这种样板。只需记录字段变量，即使它是private，并让Lombok批注生成正确记录的getter和setter。

对我来说，仅此一项好处就值得付出代价。

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

如果没有文档，调用者将不知道该方法是否有任何副作用，除了使他们的手指对遵循的明显约定无效。

我敢肯定，我不是唯一一个不幸的人，他发现一种艰难的方法，即所谓的方法setX除了设置属性之外，还可以做更多的事情。

如果在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();

评论访问者是不必要的，尤其是如果访问者不在任何地方进行任何操作时，也很浪费指尖。

如果阅读您的代码的某人不理解person.getFirstName()返回一个人的名字，则应尽一切可能将他开除。如果它做了一些数据库魔术，扔了一些骰子，打电话给名字秘书来获得名字，那么可以肯定地认为这是一项不平凡的操作，并且可以很好地记录下来。

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

如果字段名称足以说明内容，则不要放置任何内容。

通常，让代码自立，并尽可能避免注释。这可能需要重构。

编辑：上面仅指吸气剂和二传手。我相信任何不重要的事情都应该正确地javadoc'ed。

可以填写（b）部分，尤其是如果您在字段声明中添加注释以指示该字段的全部内容。

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

我总是都填写。花费在打字上的额外时间可以忽略不计，总的来说，信息多于少。