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

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 2

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.