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

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

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

public String getFoo() {
  return foo;
}

public void setFoo() {
  this foo = foo;
}

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

Answer 2

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.

Answer 3

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

Answer 4

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:

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:

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

Answer 5

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

/**
 * 
 * @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.

Answer 6

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]