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 here?
 * @param salary (1b) what do you put here?
 */
public void setSalary(float salary);

/*
 * (2a) what do you put here?
 * @return (2b)
 */
public float salary();

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?

Answer 1

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 2

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.

Answer 3

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

Answer 4

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 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 salary();

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]

Answer 7

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.

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

Answer 8

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

Answer 9

I write the javadoc at the field level to avoid repeating the text in the getter and setter (follow the DRY principle - Don't Repeat Yourself).

/** yearly gross salary */
private float salary;

You may want to reference the field level javadoc from the setter and getter.

/**
 * Setter for {@link #salary}
 */
public void setSalary(float salary);

/**
 * Getter for {@link #salary}
 */
public float salary();

Answer 10

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 setX is a standard JavaBean property setter unless you say so clearly in the documentation?

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 setX does a whole lot more than just set a property.

Answer 11

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 12

If it is a getter/setter, it should be documented.

I digress here, but if it can be made a property, perhaps that is better for simpler coding of the users of the class. I digress further but as for all the comments that have "java" anywhere in them, who said it was java? (the tags, but the question could apply anywhere really)

Answer 13

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.