Java code commenting best practices

Question

I have finalized my Java/Android project and now I need to comment the codes (mainly classes and important methods).

I need to do it by following the best industrial standards as later if someone else need to modify, it should be well staright forward.

I read many articles and found 3 main types of java commenting styles.

1. Single line comment (//.....)
2. Block comments (/* ....... */)
3. Doc comments (/** ....... */)

I read mainly about the option 2 and 3. Stack overflow discussions

So I thought of going with 2nd option as I don't need to generate HTML docs as these classes are not going to use by any other people and this is the implementation of this app.

Wonder what are the best practices in block commenting indicating "return" type, "parameters" and "breif description" of the method or class.

Would like to hear the best industrial standard practices of the java code commenting.

Thanks in advance...!!!

Answer 1

I would recommend going with the 3rd option, because if someone looks at your code for example through an IDE which supports the JavaDOCs (e.g. Eclipse), it'll show relevant information about the objects he/she examines when he/she hovers over an element that interests him/her.

This way, the developer will not have to open the actual class source file to understand what it's contract is, what does it do, or perhaps what Exceptions you have to lookout for when using it.

You can link relevant classes/methods together via JavaDOC hooks like @see.

Personally, I usually like to put DOC comments at least on my class, and public methods, for private methods I don't usually see much use for DOC comments since I don't usually generate the JavaDOC HTML. Other than DOC comments I usually tend to use the single line comments, and only use block comments when I feel like 1 sentence will not be enough to express what I wanted to, or when the print margin restrictions come into play.