Java Comments

Document Source Code with Comments

Comment operators are used to add notes and documentation to source code. Everything marked as comments is ignored by the compiler. Comments can appear anywhere in a Java source file except within character and String literals. Also, keep in mind that comments do not nest.

Three Types of Java Comments

Java has three types of comments: line, block, and JavaDoc. The first two, line and block, are used to add notes to you code that other developers can read as they are viewing your source code. This, of course, requires that they have the source code available. What if they only have a .class file? In those cases, you could add JavaDoc comments to your non-private classes, methods, and attributes. Let's look at each type of comment in turn.

Line Comment

A line comment starts with two forward slashes (//) and ends at the end of the line the slashes appear on. If the slashes are the first two characters, then the whole line is considered a comment. If they appear towards the end of the line, after non-comment code, then only the characters following the slashes are considered a comment. This second use is called "end-of-line comments" and is often used to document variable declarations.

Block Comment

A block comment starts with a forward slash and asterisk (/*) and ends with an asterisk and forward slash (*/). Anything between the delimiters is a comment, even if it spans multiple lines.

JavaDoc Comment

A JavaDoc comment is used specifically to document non-private classes, attributes, and methods. It starts with a forward slash and two asterisks (/**). It ends with one asterisk and a forward slash (*/). Everything between the delimiters is a comment, even if it spans multiple lines. The javadoc command can be used to convert a source file's JavaDoc comments into an HTML JavaDoc file. This HTML file can be packaged with the generated .class file to document the class's non-private API. For example, the following javadoc command generates an HTML JavaDoc file into the C:\home\html directory for each of the .java files listed:

javadoc -d C:\home\html Button.java Canvas.java Text.java  

Let's look at examples of the three comment types:

package arunsoft;

/**
* @author Arunkumar Subramaniam
*
* This class demonstrates use of:

* Line Comments

* Block Comments

* JavaDoc Comments.

*/
public class CommentsExample {

 /**
  * This JavaDoc comment will generate
  * documentation for
  * the greeting variable when the javadoc
  * command is executed on this class
  */
 protected static String greeting = "Hi";
 
 //JavaDoc is not applicable to
 //private methods and attributes
 private static String name = "Guys"; //Name to print
 
 public CommentsExample() {
  // Call the parent class constructor via super()
  super();
 }

 /**
  * This is the entry point of the application.
  *  main() is executed first by the JVM.
  */
 public static void main(String[] args) {
  /*
   * We don't do much in this example,
   * but if we did, we could explain
   * it with block comments like this.
   */
  System.out.println(greeting + " " + name);
 }
}

Use Comments Sparingly

Comments in source code have become more controversial with the rise in popularity of the Extreme Programming development methodology. In the past, it was widely agreed that the more comments a programmer added to his source code, the better. Extreme Programming, however, teaches that comments should only be used in exceptional circumstances. If a programmer feels the need to add comments to explain his code, he should first try to clarify the code by renaming identifiers, extracting helper methods, and otherwise simplifying the implementation. After he has exhausted other means of clarifying a bit of ugly code, then he should add a succinct comment explaining what the code does and why it could not be made more understandable. For instance, maybe the code had been optimized and he is not free to change the implementation.

Comments Degrade Over Time

So, what is wrong with extraneous code comments? At first blush, it doesn't seem that there would be any negatives to having plenty of developer comments explaining source code. The problem with extraneous comments--comments that state what should be obvious if the code were clearly written--is that when the code changes a developer must also update the accompanying comments. If he fails to do this, the comments and code will get out of synchronization. The comments become incorrect and misleading. This is almost guaranteed to happen as more than one developer modifies code over time.