Java Reference
In-Depth Information
Comments
Aprogram'ssourcecodeneedstobedocumentedsothatyou(andanyotherswhohave
to maintain it) can understand it, now and later. Source code should be documented
whilebeingwrittenandwheneveritismodified.Ifthesemodificationsimpactexisting
documentation, the documentation must be updated so that it accurately explains the
code.
Java provides the
comment
feature for embedding documentation in source code.
When the source code is compiled, the Java compiler ignores all comments—no byte-
codes are generated. Single-line, multiline, and Javadoc comments are supported.
Single-Line Comments
A
single-line comment
occupiesallorpartofasinglelineofsourcecode.Thiscomment
begins with the
//
character sequence and continues with explanatory text. The com-
pilerignoreseverythingfrom
//
totheendofthelineinwhich
//
appears.Thefollow-
ing example presents a single-line comment:
int x = (int) (Math.random()*100); // Obtain a random x co-
ordinate from 0 through 99.
Single-line comments are useful for inserting short but meaningful explanations of
sourcecodeintothiscode.Don'tusethemtoinsertunhelpfulinformation.Forexample,
when declaring a variable, don't insert a meaningless comment such as
// this
variable is an integer
.
Multiline Comments
A
multiline comment
occupiesoneormorelinesofsourcecode.Thiscommentbegins
withthe
/*
charactersequence,continueswithexplanatorytext,andendswiththe
*/
charactersequence.Everythingfrom
/*
through
*/
isignoredbythecompiler.Thefol-
lowing example demonstrates a multiline comment:
static boolean isLeapYear(int year)
{
/*
A year is a leap year if it is divisible by 400, or
divisible by 4 but
not also divisible by 100.
*/
if (year%400 == 0)
