Simple Getter/Setter comments

Question

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

/**
 * (1a) what do you put h         


        

Answer 1

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.

Answer 2

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

With Javadoc (with private option):

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

and/or

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

With Doxygen (with private extract option):

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

/** @return #salary. */
public float salary();

Answer 3

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

Answer 4

This kind of boilerplate can be avoided by using Project Lombok. Just document the field variable, even if it's private, and let Lombok annotations generate properly documented getters and setters.

For me, this benefit alone is worth the costs.

Answer 5

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

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

Very useful, if warranted:

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

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.

Answer 6

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.