Getting Started - Absolute Java - page 49

class. Within the class named System , there is a definition of an object named out . So,
the identifier System.out is used to indicate the object out (starting with a lowercase
letter for an object) that is defined in the class System (starting with an uppercase letter
for a class). This sort of dot notation will be explained later in the topic.
There is one Java convention that people new to Java often find strange. Java
programmers normally do not use abbreviations in identifiers, but rather spell things
out in full. A Java programmer would not use numStars . He or she would use
numberOfStars . A Java programmer would not use FirstProg . He or she would use
FirstProgram . This can produce long identifiers and sometimes exceedingly long
identifiers. For example, the names of two standard Java classes are BufferedReader
and ArrayIndexOutOfBoundsException . The first will be used in the next chapter
and the second will be used later in this topic. These long names cause you to do
more typing and program lines quickly become too long. However, there is a very
good reason for using these long names: There is seldom any confusion on how
the identifiers are spelled. With abbreviations, you often cannot recall how the
identifier was abbreviated. Was it BufReader or BuffReader or BufferedR or
BR or something else? Because all the words are spelled out, you know it must be
BufferedReader . Once they get used to using these long names, most programmers
learn to prefer them.

Comments
There are two ways to insert comments in a Java program. In Java, the symbols // are
used to indicate the start of a comment. All of the text between the // and the end of
the line is a comment. The compiler simply ignores anything that follows // on a line.
If you want a comment that covers more than one line, place a // on each line of the
comment. The symbols // are two slashes (without a space between them). Comments
indicated with // are often called line comments .
There is another way to insert comments in a Java program. Anything between the
symbol pair /* and the symbol pair */ is considered a comment and is ignored by the
compiler. Unlike the // comments, which require an additional // on each line, the /*
to */ comments can span several lines like so:

//comments

line
comments

/*comments*/

/*This is a multi-line comment.
Note that there is no comment symbol
of any kind on the second line.*/
Comments of the /* */ type are often called block comments . These block
comments may be inserted anywhere in a program that a space or line break is allowed.
However, they should not be inserted anywhere except where they do not distract from
the layout of the program. Usually comments are only placed at the ends of lines or on
separate lines by themselves.
Java comes with a program called javadoc that will automatically extract
documentation from the classes you define. The workings of the javadoc program
dictate when you normally use each kind of comment.
The javadoc program will extract a /* */ comment in certain situations, but it
will not extract a // comment. We will say more about javadoc and comments after

block
comments