Should I document my private methods? [closed]

Answer 1

Yes, it is necessary to document your private methods. It becomes increasingly necessary as more developers are using your code, and are modifying your code. Private methods guarente a specific functionality just like public methods. The difference is how the code is used. Documentation of private methods accelerates refactoring down the line.

Answer 2

Yes, definitely. In six months you might need to come back and do some maintenance. A couple of well-placed comments could save you a lot of time and effort. You maybe don't need to document it to the extent you would a public API but a few comments never hurt.

Answer 3

Any method that does something complex enough to be both interesting and non-obvious is worth the time to clarify it by some documentation.

Answer 4

Documenting public methods is useful for both maintainers and people who use your package.

Documenting private methods is useful for maintainers or your package (including you).

In short, it's neccessary in a slightly different way. For example, documenting private methods doesn't need to be formal.

Answer 5

What about private fields? For a Serializable class private fields must be documented. From "Effective Java" by Johsua Bloch:

Private fields define a public API, which is the serialized form of the class, and this public API must be documented. The presence of the @serial tag tells the Javadoc utility to place this documentation on a special page that documents serialized forms

Answer 6

Yes, yes, yes. Document any code that you write.

Eventually someone will be maintaining the code that you write. Documentation is a way for you to help them get into the mindset you had when writing that particular piece of code. Private functions are especially important to document because they tend to have the least amount of usages in your code from which a developer can infer their invariants.