Comments In Java

Java comments are a useful language feature, when used correctly. They can be used to give meaning to a complex segment of program code. They are also useful during development to turn off pieces of application code.

In this tutorial we’ll briefly examine comments in Java.

Java Comments

Java comments indicate to the Java compiler that it should not treat any code delimited with comments as executable code. Java supports different types of comments. These include:

  • Single Line Comments
  • Multi Line Comments
  • Documentation Comments (Javadoc)

Java Single Line Comments

A single line comment is used to comment a single line of code. A single line comment is realized by placing two forward slashes // in front of the text we wish to comment.

For example:

1
2
final int result = x + y;
// System.out.println(result);

Above we comment out line number 2 using a single line comment.

Single Line comments are also useful for explaining a segment of code.

1
final int result = x + y; //sums the variables x and y

However, comments should only be used when they provide benefit. In the above example the comment does not add benefit, as the code is easily understandable. Therefore, the comment should probably be removed.

Multi Line Comments

Multi Line comments are useful when we need to comment out more than one line of text / code.

1
2
3
4
/** This is a multi line comment
final int result = x + y; //sums the variables x and y
System.out.println(result);
**/

Java Documentation Comments

Java Documentation comments also know as Javdoc, provides a tool for describing the Java code we create.

For example, if you read the Java API documentation you are reading Javadoc. Javadoc works by enabling us to augment our code with documentation comments following the Javadoc rules.

The Javadoc tool can then be executed from the command line or as part of a build process. This tool generates html files for the code in question.

Let’s look at a simple example of describing a class.

 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
/**
 * This class represents a Person's name.  It contains fields for the different segments such as:
 * first name, middle name and list name.
 */
public class PersonName {
    private final String firstName;
    private final String middleName;
    private final String lastName;

    /**
     * Creates a new PersonName for the given first, middle and last names.
     * @param firstName the persons first name
     * @param middleName the persons middle name
     * @param lastName  the persons last name
     */
    public PersonName(final String firstName, final String middleName, final String lastName) {
        AssertUtils.strNotNullAndNotEmpty(firstName, "First name is required");
        AssertUtils.strNotNullAndNotEmpty(middleName, "Middle name is required");
        AssertUtils.strNotNullAndNotEmpty(middleName, "Last name is required");
        this.firstName = firstName;
        this.middleName = middleName;
        this.lastName = lastName;
    }

}

For example, above we document the Person class and its constructor. We can use the Javadoc tool from the command-line.

1
javadoc PersonName.java

Conclusion

In this short tutorial we briefly touched on commenting Java code. We provided an overview of the different types of comments that Java provides.