When writing Java programs, the code is not only meant for the compiler—it is also meant to be understood by other developers. In a real-world software project, multiple developers may work on the same codebase, and someone may need to understand code that was written months or even years ago.

Comments allow developers to add useful explanations and documentation directly inside the source code.

Java provides three types of comments:

1. Single-line comments — //

2. Multi-line comments — /* ... */

3. Documentation comments (Javadoc) — /** ... */

Comments are not executed as part of the program. The Java compiler ignores them when compiling the source code.

1. Single-Line Comments

A single-line comment is used when we want to add a comment on a single line.

It starts with two forward slashes:

// This is a single-line comment

Everything after // on that line is treated as a comment.

For example:

int a = 500; // This is the price of 1 kg sugar
int b = 3;   // This is the quantity available

Here, the comments explain what the variables represent.

This is particularly useful when the meaning of a variable is not immediately obvious.

Commenting Out Code

Single-line comments can also temporarily disable a line of code.

For example:

System.out.println("Hello World");

This statement prints:

Hello World

But if we write:

// System.out.println("Hello World");

Java treats the entire line as a comment, so nothing is printed.

This technique is commonly useful during debugging or testing when you temporarily don't want a particular statement to execute.

2. Multi-Line Comments

Sometimes a comment needs to span multiple lines. Instead of writing // on every line, Java provides multi-line comments.

A multi-line comment begins with:

/*

and ends with:

*/

For example:

/*
This is a multi-line comment.
Java will ignore these lines.
We can write multiple lines here.
*/

Everything between /* and */ is treated as a comment.

You can also temporarily disable multiple lines of code:

/*
int a = 500;
int b = 3;

System.out.println(a);
*/

Java ignores all of these lines.

This can be useful while experimenting with code, although large blocks of commented-out code should generally not be left in production code.

3. Javadoc Comments

The third type of comment in Java is the Javadoc comment.

Javadoc comments begin with:

/**

and end with:

*/

For example:

/**
 * Calculates the total price of the products.
 */
public int calculateTotal() {
    return 100 + 200;
}

The important difference is the additional * after the first /.

Compare:

// Single-line comment

/*
Multi-line comment
*/

/**
 * Javadoc comment
 */

Javadoc comments are specifically designed for documenting classes, methods, fields, and other program elements.

Java's Javadoc tool can process these comments and generate HTML documentation for a Java project.

Common Javadoc Tags

Javadoc supports special tags that provide structured information.

For example:

/**
 * Calculates the total price.
 *
 * @param price price of one item
 * @param quantity number of items
 * @return total price
 */
public int calculateTotal(int price, int quantity) {
    return price * quantity;
}

Here:

• @param describes a method parameter.

• @return describes the value returned by the method.

Other commonly used Javadoc tags include:

@author
@version
@param
@return
@throws
@see

For example:

/**
 * Divides two numbers.
 *
 * @param a numerator
 * @param b denominator
 * @return result of the division
 * @throws ArithmeticException if b is zero
 */
public int divide(int a, int b) {
    return a / b;
}

This documentation gives another developer useful information without requiring them to read the entire method implementation.

4. Comments vs Javadoc

Although both are comments, they serve different purposes.

For example, this is an ordinary comment:

// Calculate the total

While this is Javadoc:

/**
 * Calculates the total price.
 *
 * @param price price of one item
 * @param quantity quantity of items
 * @return total price
 */

5. When Should You Write Comments?

A common beginner mistake is thinking that more comments always mean better code.

That is not necessarily true.

Consider:

// Add 10 to age
age = age + 10;

The comment doesn't provide much additional information because the code is already obvious.

A better approach is to write comments when they explain why something is being done, rather than simply repeating what the code does.

For example:

// Add 10 years because the policy assumes the user's age after renewal.
age = age + 10;

The code tells us what happens.

The comment explains why it happens.

6. Self-Documenting Code

Good code should be understandable without requiring a comment for every line.

Compare:

int x = 500;

with:

int sugarPricePerKg = 500;

The second version is much easier to understand.

Instead of writing:

int x = 500; // Price of 1 kg sugar

we can use a meaningful variable name:

int sugarPricePerKg = 500;

This is called self-documenting code—the code communicates its purpose through meaningful names and clear structure.

Comments should complement good code, not compensate for confusing code.

7. Comments Should Be Maintained

Comments can become harmful when they no longer match the code.

For example:

// User must be 18 years old
if (age >= 21) {
    allowAccess();
}

The code and comment contradict each other.

A developer reading this code could easily become confused.

Therefore, whenever you change code, make sure related comments and documentation remain accurate.

8. Comments in Real-World Java Projects

In professional projects, comments and Javadoc are commonly useful for:

• Public APIs

• Classes and methods used by other developers

• Complex business rules

• Non-obvious algorithms

• Important assumptions

• Workarounds for external system limitations

• Configuration requirements

• Warnings about unusual behavior

However, developers generally should avoid commenting every obvious statement.

For example, this provides little value:

// Create user
User user = new User();

But this could be useful:

// Legacy API requires the username to be normalized before authentication.
String username = normalizeUsername(input);

The second comment provides context that cannot be easily understood from the code itself.

9. Key Takeaways

Java provides three types of comments:

// Single-line comment

/*
Multi-line comment
*/

/**
 * Javadoc comment
 */

Use // for short comments, /* ... */ when a comment needs multiple lines, and /** ... */ when documenting Java program elements and generating API documentation.

Most importantly, don't use comments as a replacement for good code. Use meaningful variable and method names, keep your code readable, and add comments when they provide information that the code itself cannot easily communicate.