JavaDoc for private / protected methods?

Question

Should I write JavaDoc for private or protected methods? And what about private variables?

I see class examples on my Java book and the private variables are JavaDoc'ed. So I can't understand if it is a good practice to JavaDoc the private (or protected) methods.

Answer 1

Yes you should write JavaDoc for private methods, and even when it is only for yourself. In 3 years when you have to change the code, you will be happy that you documented it.

If you leave the company, or have to work on another project, your co-workers will be happy to have a documented code. Undocumented code has much lower value.

And look how the real professionals do it. Here is an excerpt from the source code of ArrayList class by Sun Microsystems:

 /**
  * The array buffer into which the elements of the ArrayList are stored.
  * The capacity of the ArrayList is the length of this array buffer.
  */
  private transient Object[] elementData;