Getter and Setter Methods
Encounter in real Life
Should getter and setter methods be documented? More often you see things like this (if you happen to find API documentation at all):
/**
* The name.
*/
private String name;
/**
* Returns the name.
*
* @return the name.
*/
public String getName() {
...
}
/**
* Sets the name.
*
* @param name the name.
*/
public void setName(final String name) {
...
}
Interesting Information
A lot of lines with no further information. What would be nice to know what is the name used for? Are there any constraints? Is the value allowed to be null or empty or contain only whitespaces? Is any unicode character valid? Is there a minimum or maximum length?
If you are using declarative validation with annotations most of this questions are answered by the code (and this method is preferable). But if you do not use such a framework, this information may be vital to the user of your API.
Rethink
Karl Eilebrecht and Gernot Starke explain in their German book Patterns kompakt (p. 12f) another benefit of documenting simple methods such as getters and setters: You have the time to rethink the naming and the expectations from a user's view.
From their point of view their advice is to always write API comments.
What we do
In the case of getter and setter, as in the example above, we only write the documentation to the private field. Since the documentation will not show up in the public API generated by the Javadoc tool, we let a tool generate the documentation for the getter and setter methods derived from the comment written to the field. This way we have to type the API documentation only once, while the Javadoc tool can generate a complete public API.