Java Commenting Conventions

Question

Which method of commenting is most widely accepted or does it really matter?

I have been using

/**  
 * (Method description)
 * @param
 * @return
 * etc
 */

However I have read of:

Precondition:
Postcondition:

Is there a more 'professional' way of commenting?

Thanks.

Answer 1

Here are the Java coding conventions for comments recommended by Oracle:

• http://www.oracle.com/technetwork/java/codeconventions-141999.html#385

Here are Google's recommendations for their Android platform:

• http://sites.google.com/a/android.com/opensource/submit-patches/code-style-guide#javadoc

For more detailed information on style and conventions for Javadoc, see here:

• How to Write Doc Comments for the Javadoc Tool

Answer 2

The comment style in your first example is not just a convention, it is a standard for a documentation tool called Javadoc. If you follow that Javadoc commenting style, you will be able to easily generate html formatted documentation for all of your source code.

Answer 3

I would simply follow standard defined by Sun (Oracle) for writing Javadoc. Javadoc is referred by all developers unanimously :). For more information click here

I would also ask you to do following search on Stackoverflow for lots of questions and ansers on commenting.

http://stackoverflow.com/search?q=commenting