blocks|key|1523649|text|填写(b)部分是可以的，特别是如果您在字段声明处添加了注释，指明了字段的全部内容。|type|unstyled|depth|inlineStyleRanges|entityRanges|data|1523650|entityMap^0|0^^$0|@$1|2|3|4|5|6|7|D|8|@]|9|@]|A|$]]|$1|B|3|-4|5|6|7|E|8|@]|9|@]|A|$]]]|C|$]]

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.

blocks|key|1523686|text|一般没什么，如果我能帮上忙的话。Getter和setter应该是不言自明的。|type|unstyled|depth|inlineStyleRanges|entityRanges|data|1523687|我知道这听起来像是不回答，但我试着用我的时间来评论需要解释的事情。|1523688|entityMap^0|0|0^^$0|@$1|2|3|4|5|6|7|F|8|@]|9|@]|A|$]]|$1|B|3|C|5|6|7|G|8|@]|9|@]|A|$]]|$1|D|3|-4|5|6|7|H|8|@]|9|@]|A|$]]]|E|$]]

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

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

blocks|key|1523713|text|如果javadoc没有添加任何内容，我将删除javadoc并使用自动生成的注释。|type|unstyled|depth|inlineStyleRanges|entityRanges|data|1523714|entityMap^0|0^^$0|@$1|2|3|4|5|6|7|D|8|@]|9|@]|A|$]]|$1|B|3|-4|5|6|7|E|8|@]|9|@]|A|$]]]|C|$]]

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

blocks|key|1308701|text|如果字段名足以描述内容，请不要放入任何内容。|type|unstyled|depth|inlineStyleRanges|entityRanges|data|1308702|一般来说，让代码是独立的，并尽可能避免注释。这可能需要重构。|1308703|编辑:以上仅指getter和setter。我相信任何重要的东西都应该被恰当地javadoc‘。|1308704|entityMap^0|0|0|0^^$0|@$1|2|3|4|5|6|7|H|8|@]|9|@]|A|$]]|$1|B|3|C|5|6|7|I|8|@]|9|@]|A|$]]|$1|D|3|E|5|6|7|J|8|@]|9|@]|A|$]]|$1|F|3|-4|5|6|7|K|8|@]|9|@]|A|$]]]|G|$]]

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.

blocks|key|1523829|text|我通常只填充setter的param部分，以及getter的@return部分：|type|unstyled|depth|inlineStyleRanges|entityRanges|data|1523830|/**
+*+
+*+@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();|code-block|syntax|javascript|1523831|这样一来，javadoc检查工具(比如Eclipse的警告)就会干净地显示出来，而且不会出现重复。|1523832|entityMap^0|0|0|0^^$0|@$1|2|3|4|5|6|7|K|8|@]|9|@]|A|$]]|$1|B|3|C|5|D|7|L|8|@]|9|@]|A|$E|F]]|$1|G|3|H|5|6|7|M|8|@]|9|@]|A|$]]|$1|I|3|-4|5|6|7|N|8|@]|9|@]|A|$]]]|J|$]]

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

<pre><code>/**
 * 
 * @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();
</code></pre>

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

blocks|key|1308883|text|我要说的是，如果getter和setter有某种副作用，或者需要初始化之外的某种前提条件(例如:+set将从数据结构中删除一项，或者为了设置某些需要先有x和y的内容)，则只需考虑注释getter和setter。否则，这里的评论是非常多余的。|type|unstyled|depth|inlineStyleRanges|entityRanges|data|1308884|编辑:另外，如果你发现在你的getter/setter中有很多副作用，你可能想改变getter/setter的方法名(比如:+push和pop+a+stack)，谢谢你下面的评论|1308885|entityMap^0|0|0^^$0|@$1|2|3|4|5|6|7|F|8|@]|9|@]|A|$]]|$1|B|3|C|5|6|7|G|8|@]|9|@]|A|$]]|$1|D|3|-4|5|6|7|H|8|@]|9|@]|A|$]]]|E|$]]

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.

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]

blocks|key|1524019|text|注释访问器是不必要的，也是浪费指尖，特别是如果它们不在任何地方执行任何操作。|type|unstyled|depth|inlineStyleRanges|entityRanges|data|1524020|如果有人阅读你的代码不能理解person.getFirstName()返回一个人的名字，你应该尽你所能让他被解雇。如果它使用了一些数据库魔术，抛出几个骰子，调用名秘书来获得名字，那么可以放心地假设这不是一个微不足道的操作，并将其很好地记录下来。|offset|length|style|CODE|1524021|另一方面，如果你的person.getFirstName()没有返回一个人的名字...好吧，那我们就别谈这个了，好吗？|1524022|entityMap^0|0|E|L|0|9|L|0^^$0|@$1|2|3|4|5|6|7|L|8|@]|9|@]|A|$]]|$1|B|3|C|5|6|7|M|8|@$D|N|E|O|F|G]]|9|@]|A|$]]|$1|H|3|I|5|6|7|P|8|@$D|Q|E|R|F|G]]|9|@]|A|$]]|$1|J|3|-4|5|6|7|S|8|@]|9|@]|A|$]]]|K|$]]

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 <code>person.getFirstName()</code> 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.

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

blocks|key|1524050|text|我总是把两个都填上。花在键入上的额外时间可以忽略不计，一般来说，信息越多越好。|type|unstyled|depth|inlineStyleRanges|entityRanges|data|1524051|entityMap^0|0^^$0|@$1|2|3|4|5|6|7|D|8|@]|9|@]|A|$]]|$1|B|3|-4|5|6|7|E|8|@]|9|@]|A|$]]]|C|$]]

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

blocks|key|1309048|text|问问你自己，当评论以JavaDocs格式(从浏览器)查看时，你希望人们看到什么。许多人说文档是不必要的，因为它是显而易见的。如果字段是私有的，这就不成立了(除非您显式地为私有字段打开了JavaDocs+)。|type|unstyled|depth|inlineStyleRanges|entityRanges|data|1309049|在您的案例中：|1309050|public+void+setSalary(float+s)
public+float+getSalary()|code-block|syntax|javascript|1309051|目前还不清楚工资是用什么来表示的。是分，美元，英镑，还是人民币？|1309052|在记录setter/getter时，我喜欢将内容从编码中分离出来。示例：|1309053|/**
+*+Returns+the+height.
+*+@return+height+in+meters
+*/
public+double+getHeight()|1309054|第一行返回高度。返回参数记录了以米为单位的高度。|1309055|entityMap^0|0|0|0|0|0|0|0^^$0|@$1|2|3|4|5|6|7|S|8|@]|9|@]|A|$]]|$1|B|3|C|5|6|7|T|8|@]|9|@]|A|$]]|$1|D|3|E|5|F|7|U|8|@]|9|@]|A|$G|H]]|$1|I|3|J|5|6|7|V|8|@]|9|@]|A|$]]|$1|K|3|L|5|6|7|W|8|@]|9|@]|A|$]]|$1|M|3|N|5|F|7|X|8|@]|9|@]|A|$G|H]]|$1|O|3|P|5|6|7|Y|8|@]|9|@]|A|$]]|$1|Q|3|-4|5|6|7|Z|8|@]|9|@]|A|$]]]|R|$]]

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).

In your case:

<pre><code>public void setSalary(float s)
public float getSalary()
</code></pre>

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:

<pre><code>/**
 * Returns the height.
 * @return height in meters
 */
public double getHeight()
</code></pre>

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

blocks|key|1309114|text|完全没有意义--没有这些乱七八糟的代码，你会过得更好：|type|unstyled|depth|inlineStyleRanges|entityRanges|data|1309115|/**
+*+Sets+the+foo.
+*+
+*+@param+foo+the+foo+to+set
+*/
public+void+setFoo(float+foo);|code-block|syntax|javascript|1309116|非常有用，如果有保证的话：|1309117|/**
+*+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);|1309118|特别是对属性实际含义的解释在领域模型中可能是至关重要的。每当我看到满是只有投资银行家、生物化学家或量子物理学家才能理解的、名称晦涩难懂的属性时，评论解释说setGobbledygook()方法“设置了令人费解的东西”，我就想勒死某人。|1309119|entityMap^0|0|0|0|0|0^^$0|@$1|2|3|4|5|6|7|O|8|@]|9|@]|A|$]]|$1|B|3|C|5|D|7|P|8|@]|9|@]|A|$E|F]]|$1|G|3|H|5|6|7|Q|8|@]|9|@]|A|$]]|$1|I|3|J|5|D|7|R|8|@]|9|@]|A|$E|F]]|$1|K|3|L|5|6|7|S|8|@]|9|@]|A|$]]|$1|M|3|-4|5|6|7|T|8|@]|9|@]|A|$]]]|N|$]]

Absolutely pointless - you're better off without this kind of crap cluttering your code:

<pre><code>/**
 * Sets the foo.
 * 
 * @param foo the foo to set
 */
public void setFoo(float foo);
</code></pre>

Very useful, if warranted:

<pre><code>/**
 * 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);
</code></pre>

Especially the explanation of what the property actually means can be crucial in domain models. Whenever I see a bean full of properties with obscure names that only investment bankers, biochemists or quantum physicists understand, and the comments explain that the setGobbledygook() method "sets the gobbledygook.", I want to strangle someone.

blocks|key|1524218|text|为什么它们不只包含一个reference标记，让您注释来自getter和setter的字段值和引用。|type|unstyled|depth|inlineStyleRanges|entityRanges|data|1524219|/**
*+The+adjustment+factor+for+the+bar+calculation.
*+@HasGetter
*+@HasSetter
*/
private+String+foo;

public+String+getFoo()+{
++return+foo;
}

public+void+setFoo()+{
++this+foo+=+foo;
}|code-block|syntax|javascript|1524220|因此，文档适用于getter和setter以及字段(如果启用了private+javadoc)。|1524221|entityMap^0|0|0|0^^$0|@$1|2|3|4|5|6|7|K|8|@]|9|@]|A|$]]|$1|B|3|C|5|D|7|L|8|@]|9|@]|A|$E|F]]|$1|G|3|H|5|6|7|M|8|@]|9|@]|A|$]]|$1|I|3|-4|5|6|7|N|8|@]|9|@]|A|$]]]|J|$]]

Why don't they just include a reference tag to let you comment the field value and the reference from getters and setters.

<pre><code>/**
* The adjustment factor for the bar calculation.
* @HasGetter
* @HasSetter
*/
private String foo;

public String getFoo() {
 return foo;
}

public void setFoo() {
 this foo = foo;
}
</code></pre>

So that the documentation applies to the getter and setter as well as the field (if private javadocs is turned on that is).

blocks|key|1524276|text|如果getter/setter中没有特殊操作，我通常会这样写：|type|unstyled|depth|inlineStyleRanges|entityRanges|data|1524277|使用Javadoc+(带有私有选项)：|1524278|/**+Set+{@see+#salary}.+@param+{@link+#salary}.+*/
public+void+setSalary(float+salary);|code-block|syntax|javascript|1524279|和/或|1524280|/**+
+*+Get+{@see+#salary}.
+*+@return+{@link+#salary}.
+*/
public+float+salary();|1524281|使用Doxygen+(具有私人提取选项)：|1524282|/**+@param[in]+#salary.+*/
public+void+setSalary(float+salary);

/**+@return+#salary.+*/
public+float+salary();|1524283|entityMap^0|0|0|0|0|0|0|0^^$0|@$1|2|3|4|5|6|7|S|8|@]|9|@]|A|$]]|$1|B|3|C|5|6|7|T|8|@]|9|@]|A|$]]|$1|D|3|E|5|F|7|U|8|@]|9|@]|A|$G|H]]|$1|I|3|J|5|6|7|V|8|@]|9|@]|A|$]]|$1|K|3|L|5|F|7|W|8|@]|9|@]|A|$G|H]]|$1|M|3|N|5|6|7|X|8|@]|9|@]|A|$]]|$1|O|3|P|5|F|7|Y|8|@]|9|@]|A|$G|H]]|$1|Q|3|-4|5|6|7|Z|8|@]|9|@]|A|$]]]|R|$]]

If there isn't special operation in getter/setter I usually write :

With Javadoc (with private option):

<pre><code>/** Set {@see #salary}. @param {@link #salary}. */
public void setSalary(float salary);
</code></pre>

and/or

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

With Doxygen (with private extract option):

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

/** @return #salary. */
public float salary();
</code></pre>

blocks|key|1524319|text|这种样板可以通过使用Project+Lombok来避免。只需记录字段变量，即使它是private，并让Lombok注释生成记录正确的getter和setter。|type|unstyled|depth|inlineStyleRanges|offset|length|style|CODE|entityRanges|data|1524320|对我来说，光是这个好处就值得使用costs。|1524321|entityMap|0|LINK|mutability|MUTABLE|url|http://projectlombok.org/|1|http://jnb.ociweb.com/jnb/jnbJan2010.html#costbenefit^0|15|7|A|E|0|0|G|5|1|0^^$0|@$1|2|3|4|5|6|7|R|8|@$9|S|A|T|B|C]]|D|@$9|U|A|V|1|W]]|E|$]]|$1|F|3|G|5|6|7|X|8|@]|D|@$9|Y|A|Z|1|10]]|E|$]]|$1|H|3|-4|5|6|7|11|8|@]|D|@]|E|$]]]|I|$J|$5|K|L|M|E|$N|O]]|P|$5|K|L|M|E|$N|Q]]]]

This kind of boilerplate can be avoided by using <a href="http://projectlombok.org/" rel="noreferrer">Project Lombok</a>. Just document the field variable, even if it's <code>private</code>, and let Lombok annotations generate properly documented getters and setters.

For me, this benefit alone is worth the <a href="http://jnb.ociweb.com/jnb/jnbJan2010.html#costbenefit" rel="noreferrer">costs</a>.

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

<pre><code>/**
 * (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();
</code></pre>

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.

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

What do you think?

Simple Getter/Setter comments

数据结构

数据库

Eclipse

您使用什么约定来注释getter和setter？这是我很长一段时间想知道的事情，例如：/** * (1a) what do you put here? * @param salary (1b) what do you put here? */public void setSalary(float salary);/* ...

问简单的Getter/Setter注释
EN

社区

活动

资源

关于

腾讯云开发者

热门产品

热门推荐

更多推荐

问简单的Getter/Setter注释EN

社区

活动

资源

关于

腾讯云开发者

热门产品

热门推荐

更多推荐

问简单的Getter/Setter注释
EN