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