Best Practice for comments in Java source files?

Question

This doesn't have to be Java, but it's what I'm dealing with. Also, not so much concerned with the methods and details of those, I'm wondering about the overall class file.

What are some of the things I really need to have in my comments for a given class file? At my corporation, the only things I really can come up with:

• Copyright/License
• A description of what the class does
• A last modified date?

Is there anything else which should be provided?

One logical thing I've heard is to keep authors out of the header because it's redundant with the information already being provided via source control.

Update: JavaDoc can be assumed here, but I'm really more concerned about the details of what's good to include content-wise, whether it's definitive meta-data that can be mined, or the more loose, WHY etc...

Answer 1

One logical thing I've heard is to keep authors out of the header because it's redundant with the information already being provided via source control.

also last modified date is redundant

I use a small set of documentation patterns:

• always documenting about thread-safety
• always documenting immutability
• javadoc with examples
• @Deprecation with WHY and HOW to replace the annotated element
• keeping comments at minimum

Answer 2

No to the "last modified date" - that belongs in source control too.

The other two are fine. Basically concentrate on the useful text - what the class does, any caveats around thread safety, expected usage etc.

Implementation comments should usually be about why you're doing something non-obvious - and should therefore be rare. (For instance, it could be because some API behaves in an unusual way, or because there's a useful shortcut you can use but which isn't immediately obvious.)