Java Reference
In-Depth Information
1.3. Comments in Code
The English text scattered through the code is in
comments.
There are
three styles of comments, all illustrated in the
Fibonacci
example. Com-
ments enable you to write descriptive text alongside your code, annotat-
ing it for programmers who may read your code in the future. That pro-
grammer may well be
you
months or years later. You save yourself effort
by commenting your own code. Also, you often find bugs when you write
comments, because explaining what the code is supposed to do forces
you to think about it.
Text that occurs between
/*
and
*/
is ignored by the compiler. This style
of comment can be used on part of a line, a whole line, or more com-
monly (as in the example) to define a multiline comment. For single line
and part line comments you can use
//
which tells the compiler to ignore
everything after it on that line.
The third kind of comment appears at the very top, between
/**
and
*/
. A
comment starting with two asterisks is a
documentation comment
("doc
comment" for short). Documentation comments are intended to describe
declarations that follow them. The comment in the previous example is
for the
main
method. These comments can be extracted by a tool that
uses them to generate reference documentation for your classes. By con-
vention, lines within a documentation comment or a
/*...*/
comment
have a leading asterisk (which is ignored by documentation tools), which
gives a visual clue to readers of the extent of the comment.
