Lesson 9 of 50 – Comments in Java

18%

Comments in Java

Comments are notes written inside a program to explain the code. They help programmers understand, maintain, and improve their programs. Java comments are ignored by the compiler as executable instructions.

Learning Objective: Learn single-line comments, multi-line comments, documentation comments, and how to use comments effectively in Java programs.

1. What Are Comments in Java?

Comments are explanatory notes added to source code. They describe what a program or a particular statement does.

public class Hello {
    public static void main(String[] args) {
        // Display a welcome message
        System.out.println("Welcome to Java");
    }
}

Output:

Welcome to Java

The comment explains the purpose of the print statement. It does not appear in the program output.

2. Types of Comments in Java

Java supports three commonly used comment forms:

Comment Type	Symbol	Purpose
Single-line	`//`	Explains a single line or short statement.
Multi-line	`/* ... */`	Explains code across multiple lines.
Documentation	`/** ... */`	Documents program elements for tools such as Javadoc.

All three forms are useful, but documentation comments have a special role in generating API documentation.

3. Single-Line Comments

A single-line comment begins with two forward slashes (//). The comment continues until the end of that line.

public class Example {
    public static void main(String[] args) {
        // Store a number
        int number = 10;

        // Display the number
        System.out.println(number);
    }
}

Output:

Use single-line comments to explain a variable, statement, or small section of code.

4. Multi-Line Comments

Multi-line comments begin with /* and end with */. They can cover several lines.

public class Example {
    public static void main(String[] args) {
        /*
         This program displays
         a welcome message.
        */
        System.out.println("Welcome!");
    }
}

Output:

Welcome!

Multi-line comments are useful when an explanation requires more than one line.

5. Documentation Comments

Documentation comments begin with /** and end with */. They can describe classes, methods, constructors, and fields for Javadoc.

/**
 * Represents a simple calculator.
 */
public class Calculator {

    /**
     * Adds two numbers.
     *
     * @param a first number
     * @param b second number
     * @return the sum of both numbers
     */
    public int add(int a, int b) {
        return a + b;
    }
}

Javadoc can use these comments to generate HTML documentation for the class and its method.

6. Comments Beside Statements

You can also place a short comment after a statement on the same line.

int age = 20; // Student age
double price = 99.50; // Product price
boolean isActive = true; // Account status

System.out.println(age);
System.out.println(price);
System.out.println(isActive);

Output:

20
99.5
true

Keep inline comments short and useful so that they do not make code difficult to read.

7. Comments for Variables

Comments can explain the purpose of variables, especially when their meaning is not immediately clear.

public class Student {
    public static void main(String[] args) {

        // Student's full name
        String name = "Rahul";

        // Student's total marks
        int marks = 85;

        System.out.println(name);
        System.out.println(marks);
    }
}

Output:

Rahul
85

Choose meaningful variable names first. Use comments when additional explanation is helpful.

8. Comments for Methods

Comments can explain what a method does, what information it receives, and what it returns.

public class Calculator {

    // Returns the sum of two integers
    public static int add(int a, int b) {
        return a + b;
    }

    public static void main(String[] args) {
        System.out.println(add(10, 20));
    }
}

Output:

For public APIs, documentation comments are often more useful than a simple explanatory comment.

9. Comments Do Not Affect Output

Adding or removing an ordinary comment does not change the program's behavior, provided the actual code stays the same.

public class Demo {
    public static void main(String[] args) {
        // This comment is ignored as an instruction
        System.out.println("Java");

        /*
         This comment does not
         produce output either.
        */
    }
}

Output:

Java

Comments are intended for people and documentation tools, not as executable program statements.

10. Temporarily Commenting Out Code

During testing, a programmer may temporarily disable a statement by commenting it out.

public class Demo {
    public static void main(String[] args) {
        System.out.println("First message");

        // System.out.println("Second message");

        System.out.println("Third message");
    }
}

Output:

First message
Third message

The second statement does not execute because it is part of a comment.

Avoid leaving large amounts of obsolete commented-out code in finished programs. Version control is usually a better way to preserve old code.

11. Important Rules for Java Comments

// comments continue to the end of the line.
/* ... */ comments can span multiple lines.
/** ... */ comments are suitable for Javadoc documentation.
Ordinary comments do not execute as program instructions.
Block comments cannot be nested inside other block comments.
Comments should explain purpose or reasoning clearly.

Example of a block comment:

/*
This is valid.
It spans multiple lines.
*/

Incorrect nested block comment:

/*
    Outer comment
    /* Inner comment */
*/

The inner closing marker ends the block comment earlier than expected, which can cause compilation errors.

12. Good and Bad Commenting Practices

Bad example:

// Add 1 to x
x = x + 1;

This comment repeats what the code already clearly says.

More useful example:

// Move to the next page of results
pageNumber = pageNumber + 1;

A good comment explains the purpose or reason behind the operation rather than merely repeating the code.

Keep comments accurate and up to date.
Use clear and simple language.
Explain complex logic when necessary.
Avoid unnecessary comments on obvious statements.

13. Practice Program and Summary

Write a Java program using single-line, multi-line, and documentation comments.

/**
 * Demonstrates Java comments.
 */
public class CommentDemo {
    public static void main(String[] args) {

        // Store the student's name
        String name = "Rahul";

        /*
         Display the student's
         name on the screen.
        */
        System.out.println(name);
    }
}

Output:

Rahul

Summary:

Comments explain source code.
Single-line comments use //.
Multi-line comments use /* ... */.
Documentation comments use /** ... */.
Javadoc can generate documentation from documentation comments.
Good comments improve readability and maintainability.

Congratulations! You have learned the three common comment forms in Java and how to use them effectively.

Java Tutorial

Comments in Java

🧠 Quick Quiz