Should I document the self-explanatory private methods? (Java) [closed]
Asked Answered
J

2

7

I like properly documented code and it is no-brainer for me to have properly documented public methods describing the contract and same applies for private or package internal methods to explain the code internals / implementation.

However I am not sure if I should in non-public and non-protected methods:

  • adhere to all the formalities as are description of parameters, return value and exception
  • if I should document self-explanatory private methods like fireSomeEvent where is obvious what it does at first sight as this only clutters the code

What is a standard approach to this?

Judgemade answered 17/4, 2014 at 23:35 Comment(9)
I'd say do it, comments can be removed later (and restored through source control) but will be trickier to implement later, even if the method is extremely obvious.Lissner
"Self-explanatory" is a dangerous word; what's obvious to you might not be obvious to everyone else. That said, if you have a one-line method with a good name (i.e. the name reflects the purpose of the method, and not just what it happens to do), you might be able to argue that documentation adds nothing. On the other hand, a consistent documentation style helps the program appear visually consistent and makes it easier for a reader to find things; plus it means your method can be picked up by javadoc.Resound
I agree with the above, document it. You can specify when you generate the javadoc's to include private methods/variables and this will be helpful since other programmers will need to know the inner workings of the private methods.Cytochrome
There is a difference between "document" and "comment". Presumably there's no need for formal documentation, but the code should still have appropriate comments.Filing
Just think from perspective of someone who is going to use your class. Does it make sense for them to read the documentation on the method that they will never get to call or whatever?Tang
@BheshGurung When they don't see it, they don't see it. These comments are intended for other developers working on this class. And more importantly: For the one who implements it in the first place. Nothing forces you to question your own code as much as having to explain (in words) what it does.Ea
@Marco13: I didn't say no to the comments. I thought by documentation, the OP meant the javadocs. If it's about comments, then of course, the OP should put it there for the people who will have to work on the internals of the class.Tang
I think I was the one who mistakenly wrote comments. I wasn't referring to just inline or block comments but docs too- I meant comments in a Generalised sense.Lissner
Personally, if you do code voodoo, like long if statements, hexadecimal math, binary arithmetic, cryptography, etc, leave comments about what your code does. If the line is straightforward and does nothing fancy or complicated, it doesn't need a comment.Massorete
V
0

Yes.

If anyone is ever going to look at your code, document. It's worth the extra line or two. Your code will appear more consistant and clear. If anyone else ever will look at your code you should definately comment.

Even people using code look at the source code of the code, even if it is documented. This helps the client better understand the library. By adding documentation, you make your code a lot easier to understand for clients too.

Verdie answered 17/4, 2014 at 23:51 Comment(0)
T
0

I personally document anything that might cause ambiguity later. I wouldn't document

def next = counter.incrementAndGet()

as its self explanatory. Anyone who thinks you should document methods like that has too much time on their hands.

Also, in private methods, I wouldn't personally worry about adhering to Javadoc standards. Just by writing some comments you're in my good books. I don't need @param or @return. Those are for public APIs.

Transhumance answered 17/4, 2014 at 23:59 Comment(1)
is totally right. I personally woudn't write a private method that wasn't self documenting. The entire point of a private method is to hide complexity under your public api. So that the method public Account getAccountIfGrantedAccess() calls the methods checkPermissionsOfHttpRequestUser() getAccountFromDatabase() I see no reason to document anything other than what the public method has to offer to the caller.Crider

© 2022 - 2024 — McMap. All rights reserved.