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?

ps-aux
  • 11,627
  • 25
  • 81
  • 128
  • 1
    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. – ScottMcGready Apr 17 '14 at 23:40
  • 1
    "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`. – ajb Apr 17 '14 at 23:43
  • 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. – Jared Apr 17 '14 at 23:48
  • 1
    There is a difference between "document" and "comment". Presumably there's no need for formal documentation, but the code should still have appropriate comments. – Hot Licks Apr 17 '14 at 23:48
  • 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? – Bhesh Gurung Apr 17 '14 at 23:55
  • 1
    @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. – Marco13 Apr 17 '14 at 23:58
  • @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. – Bhesh Gurung Apr 18 '14 at 00:01
  • 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. – ScottMcGready Apr 18 '14 at 00:04
  • 1
    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. – Aarowaim Apr 18 '14 at 00:05

2 Answers2

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.

Anubian Noob
  • 13,426
  • 6
  • 53
  • 75
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.

sksamuel
  • 16,154
  • 8
  • 60
  • 108
  • 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. – AnthonyJClink Apr 18 '14 at 00:25