Private member variables in Java docs

Question

Why should private member variable used by getters/setters have their description specified in the javadocs describing the corresponding getters and setters.

Answer 1

The description of the private variable, like here:

/**
 * the name of this object.
 */
private String name;

... should not contain descriptions of its getters and setters. It should contain properties of this variable, invariants (like should never be null), and similar.

---

Edit: Ah, I misread your question. You asked why the description of the getters/setters should contain a description of the variable, not the other way around.

They should not - there even does not have to exist such a variable. The getters and setters should describe the effect they are having, which may include the modification (or retrieval) of some abstract property of this object. That this property is implemented by a private variable is not relevant.

Answer 2

The purpose of JavaDocs is to document the public API of your code so that developers can understand how to use your classes. It's purpose is not to expose the internal workings of your code. Documenting private members will just make you API documentation harder to read.

The meaning of private members is only of interest to those who read/maintain your code. Their purpose should be conveyed through clear, unambiguous naming and the general elegance of your code. Ideally you shouldn't even need comments.