There is also another difference between what we presented here earlier and the listing. This is the commenting of the code. Code comments are part of the program, which are ignored, filtered out by the compiler. These comments are solely for those who maintain or use the code.

In Java, there are two different comments. The code enclosed between /* and */ are comments. The start and the end of the comment do not need to be on the same line. The other type of comment starts with the // characters and ends at the end of the line.

To document the code, the JavaDoc tool can be used. JavaDoc is a special tool that reads the source code and extracts HTML documentation about the classes, methods, fields, and other entities that have a comment starting with the /** characters. The documentation will contain the JavaDoc comments in a formatted way and also the information that is extracted from the program code.

The documentation also appears as online help in the IDE when you move the mouse over a method call or class name, if there is any. The JavaDoc comment can contain HTML codes, but it generally should not. If really needed, you can use <p> to start a new paragraph or the <pre> tags to include some preformatted code sample into the documentation, but nothing more gives real benefit. Documentation should be as short as possible and contain as few formatting as possible.

There are special tags that appear in the JavaDoc documentation. These are prefilled by the IDEs when you start to type a JavaDoc as /** and then press Enter. These are inside the comment and start with the @ character. There are a predefined set of tags: @author, @version, @param, @return, @exception, @see, @since, @serial, and @deprecated. The most important tags are @param and @return. They are used to describe the method arguments and the return value. Although we are not there yet, let's peek ahead to the guessMatch method from the Guesser class.

/** 
  * A guess matches if all rows in the table matches the guess. 
  * 
  * @param guess to match against the rows 
  * @return true if all rows match 
  */ 
 protected boolean guessMatch(Color[] guess) { 
     for (Row row : table.rows) { 
         if (!row.guessMatches(guess)) { 
             return false; 
         } 
     } 
     return true; 
 }

The name of the parameter is automatically generated by the IDE. When you create the documentation, write something that is meaningful and not tautology. Many times, novice programmers feel the urge to write JavaDoc, and that something has to be written about the parameters. They create documentations like this:

* @param guess is the guess

Really? I would never have guessed. If you do not know what to write there to document the parameter, it may happen that you were choosing the name of the parameter excellent. The documentation of our preceding example will look as follows:

Focus on what the method, class, and interface does and how it can be used. Do not explain how it works internally. JavaDoc is not the place for the explanation of the algorithm or the coding. It is used to help use the code. However, if somebody happens to explain how a method works, it is not a disaster. Comments can easily be deleted.

There is, however, a comment that is worse than nothing: outdated documentation that is not valid anymore. When the contract of the element has changed, but the documentation does not follow the change and is misleading the user who wants to call the method, interface, or class whatever will face serious bugs and will be clueless.

From now on, JavaDoc comments will not be listed in print to save trees, and electrons in the eBook version, but they are there in the repository and can be examined.