137

您使用什么约定来评论 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) 部分。

你怎么看？

4

14 回答 14

186

绝对没有意义——最好不要让这种废话把你的代码弄得乱七八糟：

/**
 * 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。”时，我想扼杀某人。

于 2009-06-22T20:00:49.373 回答
93

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

于 2009-06-22T19:31:21.243 回答
38

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

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

于 2009-06-22T19:29:26.550 回答
35

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

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

于 2009-06-22T19:31:26.843 回答
13

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

在你的情况下：

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

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

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

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

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

于 2009-06-22T19:42:30.797 回答
8

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

于 2011-04-16T00:23:05.373 回答
6

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

对我来说，光是这个好处就值得付出代价。

于 2014-02-11T02:04:25.483 回答
5

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

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

我敢肯定，我不是唯一一个不幸地发现一个被调用的方法setX不仅仅是设置一个属性的困难方式。

于 2009-06-22T19:39:54.487 回答
3

如果在 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();
于 2011-10-15T23:28:03.223 回答
1

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

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

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

于 2009-06-22T19:30:25.517 回答
1

评论访问者，特别是如果他们不在任何地方做任何操作，是不必要的，而且是浪费指尖。

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

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

于 2009-06-22T19:31:50.803 回答
0

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

于 2009-06-22T19:28:20.750 回答
0

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

于 2009-06-22T19:30:06.610 回答
0

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

于 2009-06-22T19:32:24.500 回答