Introduction to Java Programming - Building Java Programs: A Back to Basics Approach - page 23

/* This comment has an asterisk/slash /*/ in it,
which prematurely closes the comment. This is bad. */
Java also provides a second comment form for shorter, single-line comments. You can
use two slashes in a row to indicate that the rest of the current line (everything to the right
of the two slashes) is a comment. For example, you can put a comment after a statement:
System.out.println("You win!"); // Good job!
Or you can create a comment on its own line:
// give an introduction to the user
System.out.println("Welcome to the game of blackjack.");
System.out.println();
System.out.println("Let me explain the rules.");
You can even create blocks of single-line comments:
// Thaddeus Martin
// Assignment #1
// Instructor: Professor Walingford
// Grader: Bianca Montgomery
Some people prefer to use the first comment form for comments that span multiple
lines but it is safer to use the second form because you don't have to remember to
close the comment. It also makes the comment stand out more. This is another case
in which, if your instructor does not tell you to use a particular comment style, you
should decide for yourself which style you prefer and use it consistently.
Don't confuse comments with the text of println statements. The text of your
comments will not be displayed as output when the program executes. The comments
are there only to help readers examine and understand the program.
It is a good idea to include comments at the beginning of each class file to indicate
what the class does. You might also want to include information about who you are,
what course you are taking, your instructor and/or grader's name, the date, and so on.
You should also comment each method to indicate what it does.
Commenting becomes more useful in larger and more complicated programs, as
well as in programs that will be viewed or modified by more than one programmer.
Clear comments are extremely helpful to explain to another person, or to yourself at a
later time, what your program is doing and why it is doing it.
In addition to the two comment forms already discussed, Java supports a particular
style of comments known as Javadoc comments. Their format is more complex, but
they have the advantage that you can use a program to extract the comments to make
HTML files suitable for reading with a web browser. Javadoc comments are useful in
more advanced programming and are discussed in more detail in Appendix C.