Java Commenting Conventions [closed]

Closed. This question is opinion-based. It is not currently accepting answers.

---

Want to improve this question? Update the question so it can 开发者_如何学编程be answered with facts and citations by editing this post.

Closed 9 years ago.

Improve this 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?

---

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:

• https://source.android.com/source/code-style.html#use-javadoc-standard-comments

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

• How to Write Doc Comments for the Javadoc Tool

---

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.

---

This link is very useful and i have been using this for a long time and has helped me a lot. This creates a very good and documented code with maximum readiblity.

---

First off all having readable code and readable comments are two things that are totally different.

Readable code is code the uses good variable, method, class names, etc.

Readable comments are more a matter of personal taste. Some people like comments to follow grammatical rules that would be used to write a book while others couldn't care less about grammatical stuff. You can go through this link:

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

From readable code and comments, you can create documentation with the help of doxygen.

http://www.doxygen.nl/manual/docblocks.html

---

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.

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