In this tutorial, you will learn about comments in Java and why and how to use them.

In programming, comments are considered part of the program and are used to understand the code. However, Java compilers completely ignore them and do not execute them.

So in the Java programming language, there are two types of comments:

/ *… * /
//….

Common comment /*…….*/

This is a multi-line comment that can be multiple lines. The Java compiler ignores everything from / * to * /. For example,

1. / * This is a multi-line comment.
2. * The problem prints “Hello, World!” to the standard output.
3. * /
4. class HelloWorld {
5. public static void main (String [] args) {
6. {
7. System.out.println (“Hello, World!”);
8. }
9. }
10. }

In the above code, the comment is equal to:

/ * This is a multi-line comment.

* The problem prints “Hello, World!” to the standard output.

* /

One line comment //

The compiler ignores everything from // to the bottom of the line. For example,

1. // “Hello, World!” program
3. class AssignmentOperator {
4. public static void main (String [] args) {
5. {
6. System.out.println (“Hello, World!”); // prints “Hello, World!”
7. }
8. }
9. }

The above program includes two one-line comments:

//"Hello, World!”"program

And

// prints "Hello, World!"

Use the comments in the right way

Comments should not be a substitute for explaining poorly written code in English. Write code with good structure and readability, and use comments.

Some believe the code should be documented and there should be few comments. However, we are completely against this (this is our personal opinion). There is no problem with using comments to explain complex algorithms, regex, or scenarios.

Use comments to explain “why” instead of “how.”

Types of Java Comments

Commenting code is a good practice for Java developers, enhancing code readability and maintainability. Java provides three types of comments:

1. Inline (Single-line) Comments → //
2. Block (Multi-line) Comments → /* ... */
3. JavaDoc Comments → /** ... */

Inline Comments (//)

Also known as single-line comments, inline comments start with // and only affect the code on that particular line.

Example:

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

  public static void main(String[] args) {
    System.out.println("This line will run.");
    //System.out.println("This line will not run.");
  }
}

Sometimes, inline comments are placed at the end of a line to clarify a variable or operation:

int number = 10;  // Initialize number to 10

Block Comments (/* ... */)

Block or multi-line comments allow developers to comment out multiple lines at once. This is useful for temporarily turning off code or adding detailed explanations.

Example:

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

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

JavaDoc Comments (/** ... */)

JavaDoc comments are designed explicitly to generate documentation. Unlike inline or block comments, which are meant for developers maintaining the code, JavaDoc comments help users understand how to use a class or method.

Example:

/** This JavaDoc comment describes the class. */
public class JavaCommentsExample {

  /** This JavaDoc comment describes the method. */
  public static void main(String[] args) {
    System.out.println("This line will run.");  // Inline comment
    /* System.out.println("This is in a block comment."); */
  }
}

Best Practices for Using Java Comments

• Use JavaDoc (/** ... */ To describe classes and methods that need documentation.
• Use inline comments (//) for brief explanations of specific lines.
• Use block comments (/* ... */to comment out multiple lines when necessary.

While well-written code should be self-explanatory, good developers use comments wisely to enhance clarity.

Multi-line Comments in Java

Multi-line comments allow developers to write explanatory notes that span several lines. To create a multi-line comment, use the /* ... */ syntax.

Example: Multi-line Comment

/* This is a multi-line comment.
 * The program prints "Hello, World!" to the standard output.
 */

class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello, World!");
    }
}

Output:

Hello, World!

In this example, the Java compiler ignores everything within /* ... */, making it helpful to add detailed descriptions or temporarily turn off large code sections.

Preventing Code Execution Using Comments

During debugging, if a portion of code produces errors, we can use comments to prevent its execution instead of deleting it.

Example: Debugging with Comments

public class Main {
    public static void main(String[] args) {
        System.out.println("some code");
        // System.out.println("error code"); // Commented out for debugging
        System.out.println("some other code");
    }
}

Using // Before problematic code, temporarily disable it without removing it, making it a valuable debugging strategy.

Why Use Comments?

• Improve Code Readability: Makes the code easier to understand for future reference.
• Assist in Debugging: Helps identify and prevent errors during Development.
• Enhance Collaboration: Allows peer developers to comprehend the code structure efficiently.