Commenting Java Code

Comments are essential to good programming. Every file containing code should start with a comment justifying its existence. Comments should be sprinkled liberally throughout every file explaining the purposes and goals of every block of code that is not obvious. When you are in a hurry to finish a task, documenting what you are doing is not glamorous, but years later when you need to go make a fix for yourself or a customer, you’ll be very glad you took the time to comment your code.

Comments are ignored by the ‘javac’ command. The compiler does not care what you put into a comment. You can even put code into a comment and the ‘javac’ command will pretend it doesn’t exist.

Java has three commonly used types of comments. There are the single-line comments, multi-line comments, and Javadoc comments. They are all useful. However, Javadoc comments are the most powerful, because technical documentation for your code can be automatically generated from them.

Single-Line Comments

Single-line comments start with two forward slashes on each line. That would be // followed by some text. The forward slashes can appear anywhere on the line. However, only the text after the forward slashes are comments. That means that you can mix code and comments on the same line, as long as the comments are last.

Here is a typical single-line comment.

1
2
3
4
// The Alert is used for displaying information 
// to users
Alert al = new Alert( AlertType.INFORMATION );
 

Single-line comments lend themselves to use with pseudocode. Think of pseudocode as a list of coding tasks. You can write down a list of tasks you need to write code for with each task on its own line. Then fill in the code between the single-line comment list of tasks. The result is that after you finish writing your code, you already have comments for what you did.

Multi-Line Comments

If you are writing a lot of comments, or a long description, often you want to use a multi-line comment. It is not unheard of for complex programs to place text based art or diagrams in multi-line comments to help programmers visualize how a networking protocol or other type of coding task is assembled.

A multi-line comment begins with a forward slash and an asterisk (/*) and ends with an asterisk and a forward slash (*/). Often programmers add additional symbols just to make the comment stand out. I’ve even seen 3D text based graphics in multi-line comments.

Below is a typical multi-line comment.

1
2
3
4
5
6
7
8
9
    al.setHeaderText( null );
    /*
      You could put any information you want here,
      without feeling restricted by line count, or
      even needing to remember to add forward slashes
      to the front of your message.
    */
    al.setContentText( "Hello World :-)" );
    al.showAndWait();

Javadoc Comments

By far, the most common comment type used in Java is the Javadoc comment. Javadoc comments are a specially type of multi-line comment used in Java to generate technical documents for source code. Every professional Java program uses extensive Javadoc comments. Javadoc comments have so many features that you could write an entire book just on how to make great Javadoc comments.

Javadoc comments begin with a forward slash and two asterisks, and end with a single asterisk followed by a single forward slash. By convention, each line of the Javadoc comment contains an asterisk before any tags or text on the line.

Javadoc comments typically go at the beginning of class, variable, and method definitions. (I’ll describe more on classes, variables, and methods in a future post.) If you write a comment for any part of your code that is not a definition, then use the regular single-line comments or multi-line comments.

Here is a typical Javadoc comment.

1
2
3
4
5
6
7
/**
 * The purpose of this app is to prove JavaFX
 * works on this computer.
 * 
 * @author T. Gene Davis
 */
public class HelloWorld extends Application {

To compile the Javadocs for one *.java file, use the ‘javadoc’ command. You will always want to specify a directory to put your Javadocs into with the ‘-d </some/directory>’ option. The ‘javadoc’ command creates a lot of web pages and supporting files, so you want to contain them in a directory that you don’t mind containing a lot of clutter.

If you want to create a Javadoc of the a file named HelloWorld.java in the directory ‘docs’,

  1. Open a command line and navigate to the directory with the ‘HelloWorld.java’ file.
  2. Type the following:

javadoc -d ./docs HelloWorld.java
  1. Navigate to the newly created ‘docs’ folder.
  2. Open the index.html file in a web browser to see the Javadocs

Summary

The following sample code has two Javadoc comments, two single-line comments, and one multi-line comment.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
import javafx.application.Application;
import javafx.scene.control.Alert;
import javafx.scene.control.Alert.AlertType;
import javafx.stage.Stage;

/**
 * The purpose of this app is to prove JavaFX
 * works on this computer.
 * 
 * @author T. Gene Davis
 */
public class HelloWorld extends Application {

  /**
   * All the action starts here in JavaFX.
   */
  @Override
  public void start(Stage primaryStage) {
		
    // The Alert is used for displaying information 
    // to users
    Alert al = new Alert( AlertType.INFORMATION );
    al.setHeaderText( null );
    /*
      You could put any information you want here,
      without feeling restricted by line count, or
      even needing to remember to add forward slashes
      to the front of your message.
    */
    al.setContentText( "Hello World :-)" );
    al.showAndWait();
		
  }

  public static void main(String[] args) {
    launch(args);
  }
	
}

The Javadoc comments are at the beginning of the HelloWorld class definition and the ‘start’ method definition. When Javadoc comments are created with the ‘javadoc’ command, the multi-line and single-line comments are ignored. Only the Javadoc comments are kept for the the technical documents created by the ‘javadoc’ command.

Suggested Tasks

1) Use javadoc comments, multiline comments, and single line comments to comment one of the applications you wrote in the last tutorial.

2) Make a list of tasks using single-line comments.

3) Use the javadoc command to create javadocs for a program you wrote.