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

我通常只为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 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。”，我想扼杀某人。

Answer 3

一般来说，没有，如果我可以帮助它。吸气剂和二传手应该是不言自明的。

我知道这听起来像是一个非答案，但我试着用我的时间来评论需要解释的事情。

Answer 4

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

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

Answer 5

问问自己，当评论被视为JavaDocs（来自浏览器）时，您希望人们看到什么。许多人说文档没有必要，因为它很明显。如果字段是私有的，则不会成立（除非您明确为私有字段启用JavaDocs）。

在你的情况下：

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

目前尚不清楚薪水表示的是什么。它是美分，美元，英镑，人民币？

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

/**
 * 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。

对我来说，仅凭这个好处值得费用。

Answer 8

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

如果没有文档，调用者就不会知道该方法是否有任何副作用，除非他们指责所遵循的明显惯例。

我确信我不是唯一一个不幸发现一个名为 setX 的方法不仅仅是设置属性的方法。 / p>

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

如果字段名称足以描述内容，请不要放置任何内容。

一般来说，让代码自立，并尽可能避免评论。这可能需要重构。

编辑：以上仅指吸气剂和制定者。我相信任何不平凡的事都应该适当地进行javadoc。

Answer 12

可以填写（b）部分，特别是如果你在字段声明上发表评论，指出字段的全部内容。

Answer 13

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

Answer 14

我总是填写两个。打字所花费的额外时间可以忽略不计，一般而言，更多信息优于更少。

Answer 15

如果是getter / setter，则应记录下来。

我离题了，但如果它可以成为一个属性，也许这对于类的用户的简单编码更好。 我进一步讨论了所有有“java”的评论。在他们的任何地方，谁说这是java？ （标签，但问题可以适用于任何地方）