Java 简单的 Getter/Setter 注释

Simple Getter/Setter comments

提问by ThaDon

What convention do you use to comment getters and setters? This is something I've wondered for quite some time, for instance:

你使用什么约定来评论 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();

I always find I'm pretty much writing the exact same thing for 1a/b and 2a/b, something like 1a) Sets the salary of the employee, 1b) the salary of the employee. It just seems so redundant. Now I could see for something more complex you might write more in the (a) parts, to give context, but for a majority of the getters/setters out there the wording is almost exactly the same.

我总是发现我为 1a/b 和 2a/b 写了几乎完全相同的东西，比如 1a) 设置员工的工资，1b) 员工的工资。这似乎太多余了。现在我可以看到一些更复杂的东西，你可能会在 (a) 部分写更多，以提供上下文，但对于大多数 getter/setter 来说，措辞几乎完全相同。

I'm just curious if, for the simple getters/setters its ok to only fill in either the (a) part OR the (b) part.

我只是好奇，对于简单的 getter/setter，是否可以只填写 (a) 部分或 (b) 部分。

What do you think?

你怎么认为？

采纳答案by sleske

I usually just fill the param part for setters, and the @return part for getters:

我通常只为 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();

That way javadoc checking tools (such as Eclipse's warnings) will come out clean, and there's no duplication.

这样 javadoc 检查工具（例如 Eclipse 的警告）就会干净利落，并且没有重复。

回答by akf

it is ok to fill in the (b) part, especially if you put a comment at the field declaration indicating what the field is all about.

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

回答by Eric Wendelin

Generally nothing, if I can help it. Getters and setters ought to be self-explanatory.

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

I know that sounds like a non-answer, but I try to use my time for commenting things that need explanation.

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

回答by Alex B

If the javadoc does not add anything, I delete the javadoc and use the auto-generated comments.

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

回答by Thorbj?rn Ravn Andersen

Don't put anything if the field name is suficiently descriptive of the contents.

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

Generally, let the code be self standing, and avoid commenting if at all possible. This may require refactoring.

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

EDIT: The above refers to getters and setters only. I believe anything non trivial should be properly javadoc'ed.

编辑：以上仅指 getter 和 setter。我相信任何重要的事情都应该正确地使用 javadoc。

回答by Gopherkhan

I'd say only worry about commenting getters and setters if they have some sort of side effect, or require some sort of precondition outside of initialization (i.e.: getting will remove an item from a data structure, or in order to set something you need to have x and y in place first). Otherwise the comments here are pretty redundant.

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

Edit: In addition, if you do find a lot of side effects are involved in your getter/setter, you might want to change the getter/setter to have a different method name (ie: push and pop for a stack) [Thanks for the comments below]

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

回答by Henrik Paul

Commenting accessors, especially if they don't do any operations anywhere, is unnecessary and a waste of fingertips.

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

If someone reading your code can't understand that person.getFirstName()returns the first name of a person, you should try everything in your powers to get him fired. If it does some database magic, throws a few dice, calls the Secretary of First Names to get the first name, It's safe to assume it's a non-trivial operation, and document it well.

如果有人阅读你的代码不能理解person.getFirstName()返回一个人的名字，你应该尽你所能让他被解雇。如果它执行了一些数据库魔术，扔了几个骰子，调用名字秘书来获取名字，可以安全地假设它是一个非平凡的操作，并将其记录在案。

If, on the other hand, your person.getFirstName()doesn't return a person's first name... well, let's not go there, shall we?

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

回答by Paul Sonier

I always fill in both. The additional time spent typing is negligible, and more information is better than less, in general.

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

回答by oxbow_lakes

I'm really disappointed about the answers basically saying comprehensive documenting is a waste of time. How are clients of your API supposed to know that a method called setXis a standard JavaBean property setterunless you say so clearly in the documentation?

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

Without documentation, a caller would have no idea whatsoever if the method had any side effects, other than by crossing their fingers about the apparent convention being followed.

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

I'm sure I'm not the only one here to have had the misfortune to find out the hard way that a method called setXdoes a whole lot more than just set a property.

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

回答by Steve Kuo

Ask yourself what do you want people to see when the comments are viewed as JavaDocs (from a browser). Many people say that documentation is not necessary since it's obvious. This won't hold if the field is private (unless you explicitly turn on JavaDocs for private fields).

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

In your case:

在你的情况下：

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

It's not clear what salary is expressed in. It is cents, dollars, pounds, RMB?

不清楚薪水是用什么表示的，是美分、美金、英镑、人民币？

When documenting setters/getters, I like to separate the what from the encoding. Example:

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

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

The first line says it returns the height. The return parameter documents that height is in meters.

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