First one is for Javadoc you define on the top of classes, interfaces, methods etc. You can use Javadoc as the name suggest to document your code on what the class does or what method does etc and generate report on it.
Second one is code block comment. Say for example you have some code block which you do not want compiler to interpret then you use code block comment.
another one is // this you use on statement level to specify what the proceeding lines of codes are supposed to do.
There are some other also like //TODO, this will mark that you want to do something later on that place
//FIXME you can use when you have some temporary solution but you want to visit later and make it better.
Hope this helps
The first is Javadoc comments. They can be processed by the javadoc
tool to generate the API documentation for your classes. The second is a normal block comment.
Comments in the following listing of Java Code are the greyed out characters:
/**
* The HelloWorldApp class implements an application that
* simply displays "Hello World!" to the standard output.
*/
class HelloWorldApp {
public static void main(String[] args) {
System.out.println("Hello World!"); //Display the string.
}
}
The Java language supports three kinds of comments:
/* text */
The compiler ignores everything from /*
to */
.
/** documentation */
This indicates a documentation comment (doc comment, for short). The compiler ignores this kind of comment, just like it ignores comments that use /*
and */
. The JDK javadoc tool uses doc comments when preparing automatically generated documentation.
// text
The compiler ignores everything from //
to the end of the line.
Now regarding when you should be using them:
Use // text
when you want to comment a single line of code.
Use /* text */
when you want to comment multiple lines of code.
Use /** documentation */
when you would want to add some info about the program that can be used for automatic generation of program documentation.
Reading the section 3.7 of JLS well explain all you need to know about comments in Java.
There are two kinds of comments:
- /* text */
A traditional comment: all the text from the ASCII characters /* to the ASCII characters */ is ignored (as in C and C++).
- //text
An end-of-line comment: all the text from the ASCII characters // to the end of the line is ignored (as in C++).
About your question,
The first one
/**
*
*/
is used to declare Javadoc Technology.
Javadoc is a tool that parses the declarations and documentation comments in a set of source files and produces a set of HTML pages describing the classes, interfaces, constructors, methods, and fields. You can use a Javadoc doclet to customize Javadoc output. A doclet is a program written with the Doclet API that specifies the content and format of the output to be generated by the tool. You can write a doclet to generate any kind of text file output, such as HTML, SGML, XML, RTF, and MIF. Oracle provides a standard doclet for generating HTML-format API documentation. Doclets can also be used to perform special tasks not related to producing API documentation.
For more information on Doclet
refer to the API.
The second one, as explained clearly in JLS, will ignore all the text between /*
and */
thus is used to create multiline comments.
Some other things you might want to know about comments in Java
/* and */
have no special meaning in comments that begin with //
.//
has no special meaning in comments that begin with /* or /**
.Thus, the following text is a single complete comment:
/* this comment /* // /** ends here: */
I don't think the existing answers adequately addressed this part of the question:
When should I use them?
If you're writing an API that will be published or reused within your organization, you should write comprehensive Javadoc comments for every public
class, method, and field, as well as protected
methods and fields of non-final
classes. Javadoc should cover everything that cannot be conveyed by the method signature, such as preconditions, postconditions, valid arguments, runtime exceptions, internal calls, etc.
If you're writing an internal API (one that's used by different parts of the same program), Javadoc is arguably less important. But for the benefit of maintenance programmers, you should still write Javadoc for any method or field where the correct usage or meaning is not immediately obvious.
The "killer feature" of Javadoc is that it's closely integrated with Eclipse and other IDEs. A developer only needs to hover their mouse pointer over an identifier to learn everything they need to know about it. Constantly referring to the documentation becomes second nature for experienced Java developers, which improves the quality of their own code. If your API isn't documented with Javadoc, experienced developers will not want to use it.
Java supports two types of comments:
/* multiline comment */
: The compiler ignores everything from /*
to */
. The comment can span over multiple lines.
// single line
: The compiler ignores everything from //
to the end of the line.
Some tool such as javadoc use a special multiline comment for their purpose. For example /** doc comment */
is a documentation comment used by javadoc when preparing the automatically generated documentation, but for Java it's a simple multiline comment.
For the Java programming language, there is no difference between the two. Java has two types of comments: traditional comments (/* ... */
) and end-of-line comments (// ...
). See the Java Language Specification. So, for the Java programming language, both /* ... */
and /** ... */
are instances of traditional comments, and they are both treated exactly the same by the Java compiler, i.e., they are ignored (or more correctly: they are treated as white space).
However, as a Java programmer, you do not only use a Java compiler. You use a an entire tool chain, which includes e.g. the compiler, an IDE, a build system, etc. And some of these tools interpret things differently than the Java compiler. In particular, /** ... */
comments are interpreted by the Javadoc tool, which is included in the Java platform and generates documentation. The Javadoc tool will scan the Java source file and interpret the parts between /** ... */
as documentation.
This is similar to tags like FIXME
and TODO
: if you include a comment like // TODO: fix this
or // FIXME: do that
, most IDEs will highlight such comments so that you don't forget about them. But for Java, they are just comments.
Source: Stackoverflow.com