Should I document self-evident private methods? (Java)

Question

I like properly documented code, and for me there is no problem with properly documented public methods that describe the contract, and the same applies for the internal or internal methods of the package to explain the internal components / implementation of the code.

However, I am not sure if I should use non-public and insecure methods:

• adhere to all formalities like parameter description, return value and exception
• if I have to document self-evident private methods like fireSomeEvent , where it is obvious what it does at a glance, as this only clutters the code

What is the standard approach to this?

Answer 1

Yes.

If anyone ever wants to see your code, document. It costs an extra line or two. Your code will become more consistent and understandable. If anyone else looks at your code, you should definitely comment.

Even people using the code look at the source code of the code, even if it is documented. This helps the customer better understand the library. By adding documentation, you make the code much clearer for clients.

Answer 2

I personally document everything that can cause ambiguity later. I would not document

def next = counter.incrementAndGet()

as self-evident. Anyone who thinks you should document such methods has too much time in their hands.

In addition, in private methods, I would not personally worry about complying with Javadoc standards. Just by writing a few comments you are in my good books. I don't need @param or @return. This is for public APIs.