JavaDoc for private / protected methods? [closed]

Question

Closed. This question is opinion-based. It is not currently accepting answers.

---

Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.

Closed 6 years ago.

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

The first question you need to ask yourself is "why write JavaDocs at all?" Who are they useful for? Who asked you to write them?

Most likely, someone (employer / professor) asked you to document some of your methods. This is generally A Good Thing, but comes with a cost: additional maintenance.

If you have a publicly accessible version of your docs (such as if you're generating them and publishing them online for end-users), it makes sense to document anything your end users will need to know. This includes all public classes and methods.

What about for yourself, and other developers?

My opinion is that you shouldn't use javadocs on internal and private methods and classes. The main reason is that javadocs primarily benefit people who consume, not maintain, your code.

On the other hand, you do need to keep notes and comments on your own code, which is often internal. In this case, I would suggest normal comments (eg. //) instead; it's less maintenance, and often, equally clear, with a lot less typing.

On the other hand, if a method becomes public, it can be useful to convert those comments into a true javadocs. Javadocs have the benefit of forcing you to think about (and document) every parameter, exception, and return value.

The trade-off is yours to make.

Answer 2

Nope, you shouldn't write javadoc for private methods. End users don't have access to private fields or methods so there really isn't a point in providing javadoc for them. Private fields and methods are only meant for the developer. If you really need to though, feel free to write comments for non-obvious logic. You should probably write javadoc for protected methods because these methods are sometimes overridden and it is helpful to provide the user with some information about what the method does, or, should do.

Answer 3

You often hear the general recommendation that, in the best case, comments should simply not be necessary at all. But concerning JavaDoc, they play an important role not only for the developer, but also for the user of the library.

Additionally, writing JavaDoc comments may be more useful for you (especially for a beginner) than for anyone else: When you find it hard to describe what a variable is or what a method does with a single /** One-line-JavaDoc comment */, then you'll automatically re-think what you have done there.

When generating JavaDocs, you may choose whether you want to generate them only for the public and protected parts of the API, or also for default- or private elements.

However, you should in any case document protected methods: May someone who extends the class only call this method, or is he also allowed to override this method? If so, are there any pre- and postconditions that he should know about? Should he call super.theMethod() in the overridden version? (BTW: If he's not allowed to override the method, then it should be final, but documented anyhow)

BTW: I personally comment everything, but know that most people think it's not necessary or even a bad style, especially for "trivial" things

/**
 * The number of elements in this set
 */
private final int numberOfElements;

I think it does not harm, but helps in many cases. Maybe, regarding private parts, it's just a matter of taste.

Answer 4

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;

Answer 5

You don't have to javadoc anything, but it's very helpful to. More javadocs are never a bad thing.

Per your question, if you use the javadoc documentation compiler, javadocs will be compiled for protected methods, but not private methods. There's no reason they can't still be used as code comments, though.