Ivor Horton's Beginning Java™ 2, JDK™ 5th Edition

2.14. Program Comments

I have been adding comments in all the examples so far, so you already know that everything following // in a line is ignored by the compiler (except when the // appears in a character string between double quotes of course). Another use for // is to change lines of code into comments so that they don't get executed—to "comment them out" in other words. If you want to remove some code from a program temporarily, you just add // at the beginning of each line that you want to eliminate. Removing the // later restores the line of code.

It is often convenient to include multiple lines of comment in a program—for example, at the beginning of a method to explain what it does. An alternative to using // at the beginning of each line in a block of comments is to put /* at the beginning of the first comment line and */ at the end of the last comment line. Everything between the /* and the next */ will be ignored. By this means you can annotate your programs, as shown here for example:

/***************************************
 * This is a long explanation of       *
 * some particularly important         *
 * aspect of program operation.        *
 ***************************************/

Here I have used asterisks to highlight the comment. Of course, you can frame blocks like this in any way that you like, or even not at all, just so long as there is /* at the beginning and */ at the end.

2.14.1. Documentation Comments

You can also include comments in a program that are intended to produce ...