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 getSalary();
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?
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.