Java comment types by example

Types of Java comments

Good Java programmers comment their code.

To facilitate that process, the JDK offers developers a choice of three Java comment types:

1. Inline Java comments, which begin with two slashes //
2. Block Java comments, which follow the structure /*   */
3. JavaDoc comments on methods and classes /**  */

Single line Java comment example

Inline comments, also known as single-line Java comments, begin with two slashes, and only impact the code on the line in which they appear.

The following is an example of a single-line comment in Java:

public class JavaCommentsExample {
  // This is a single-line Java comment

  public static void main(String[] args) {

    System.out.println("This line will run.");
    //System.out.println("This line will not run.");

  }
}

The two green lines of code in the above example demonstrate the use of single-line comments.

Sometimes an inline Java comment is placed after a piece of code to be executed, like this:

int number = 10;  //initialize number to 10

A single-line comment only affects the code that comes after it, not any code that precedes it.

Java block comment example

Inline comments in Java only effect the line of code on which they appear.

But sometimes developers want to comment out multiple lines of code at once. A developer might even want to comment out an entire method.

This is where Java block comments, or multi-line comments, come in handy.

Using a slash star (/*), star slash (*/) syntax, a block comment in Java can span multiple lines, and include both code and text.

Here is an example of how to use Java block comments:

public class JavaCommentsExample {
  /* This block comment spans only one line. */
  public static void main(String[] args) {
    System.out.println("This line will run.");

    /* This block comment spans multiple lines.
       System.out.println("This line will not run.");
       System.out.println("This line will not run.");
       None of the code in this Java block comment will run.
    */

  }
}

JavaDoc comments in Java

JavaDoc comments, which use a slash-star-star, star-slash ( /**  …  */ ) syntax, serve a different purpose from inline comments and multi-line Java comments.

Whereas inline and block Java comments are read by other developers who maintain the code, JavaDoc comments are for developers who use your code.

You can only place JavaDoc comments before the class declaration or a method declaration. Also, they describe the purpose of the class or method and how it might be used.

Unlike block and single-line Java comments, JavaDoc does not include any implementation details.

When Java code is ready to ship, a special JavaDoc utility processes the JavaDoc comments on every file in the codebase, and generates documentation for users of your code to read.

JavaDoc comment example

The following code includes two JavaDoc comments, along with both inline and block Java comments to demonstrate that it is allowable to mix all three types together:

/** This JavaDoc comment should describe the class. */
public class JavaCommentsExample {

  /** This JavaDoc comment should describe the method. */
  public static void main(String[] args) {

    System.out.println("This line will run.");  // Java comment
    /* System.out.println("This is in a Java block comment."); */

  }
}

How to use Java comments

To use Java comments effectively, follow these steps:

1. If the comment describes how to use the code, use JavaDoc comments /** */
2. If the comment only spans one line, use an inline comment //
3. If the comment spans multiple lines, use a block comment /*  */

There’s an old saying: good code comments itself. This sentiment has some merit.

But at the same time, good programmers comment their code.

Add Java comments to your code judiciously, when and where makes sense. This helps others understand the code you write.