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

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.)

Answer 2

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 3

For the sanity of yourself and future developers, you really ought to be writing Javadocs.

Answer 4

An overall description of the purpose of the class, a description for each field and a contract for each method. Javadoc format works well.

Answer 5

When you feel the need to write comments to explain what some code does, improve the readability of the code, so that comments are not needed. You can do that by renaming methods/fields/classes to have more meaningful names, and by splitting larger methods into smaller methods using the composed method pattern.

If even after all your efforts the code is not self-explanatory, for example the reason why some unobvious code had to be written is not clear from the code, then apologize by writing comments. (Sometimes you can document the reasons by writing a test which will fail, if somebody changes the unobvious-but-correct code to do the obvious-but-wrong thing. But having a comment in addition to that is also useful. I prefix such comments often with "// HACK:" or "// XXX:".)

Answer 6

If you assign ownership of components to particular developers or teams, owners should be recorded in the component source or VCS metadata.