Geek Answers Handbook

Best practice for comments in Java source files?

It does not have to be Java, but it is what I am dealing with. In addition, I am not very versed in the methods and details of these questions; I am interested in the general class file.

What are some of the things that I really need in my comments for this class file? In my corporation, the only thing I can really come up with:

  • Copyright / License
  • Description of what the class does
  • Last modified date?

Is there anything else that needs to be provided?

One of the logical things I've heard is to leave the authors out of the title because it is redundant with the information already provided through the source control.

Update: JavaDoc can be assumed here, but I'm more concerned about information about what is good to include in the content, whether it is the final metadata that can be extracted, or more free, WHY, etc ....

+5
source share
6 answers

One logical thing I've heard is to leave authors out of the title because it is redundant with information already provided through source control.

also last modified date redundant

I use a small set of documentation templates:

  • always documents thread safety
  • always documents immutability
  • javadoc with examples
  • @ Note with WHY and HOW to replace annotated element
+14

" " - .

. - , - , ..

, - - . (, , API , , , .)

+6

Javadocs.

+2

, , - , , . , //, , .

, , , - , , , . ( , , , - , , , , . "//HACK:" "//XXX:".)

+2

, . Javadoc .

0

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

0
source

More articles:


All Articles