Java Comments — Single-line, Multi-line & Javadoc

Comments are notes you write for humans — the compiler ignores them completely. Good comments explain why something is done, not what is done.

---

Single-Line Comments

Use // to comment out the rest of a line:

int age = 25;  // user's age in years

// This line is completely a comment
// int debug = 1;  // commented-out code

---

Multi-Line Comments

Use /* ... */ for longer blocks:

/*
 * This method calculates the total price
 * including tax and shipping costs.
 * It returns the final amount as a double.
 */
double calculateTotal(double price, double tax) {
    return price + (price * tax);
}

Multi-line comments cannot be nested. /* outer /* inner */ oops */ will cause an error.

---

Javadoc Comments

Use /** ... */ to generate API documentation. These are placed before classes, methods, and fields.

/**
 * Represents a bank account with basic operations.
 *
 * @author Sushil Verma
 * @version 1.0
 * @since 2024-01-01
 */
public class BankAccount {

    /**
     * Deposits money into the account.
     *
     * @param amount the amount to deposit (must be positive)
     * @return the new balance after deposit
     * @throws IllegalArgumentException if amount is negative
     */
    public double deposit(double amount) {
        if (amount < 0) {
            throw new IllegalArgumentException("Amount must be positive");
        }
        balance += amount;
        return balance;
    }
}

Common Javadoc Tags

Tag	Purpose
@param name	Describes a method parameter
@return	Describes the return value
@throws ExceptionType	Documents an exception
@author	Author name
@version	Version number
@since	When it was introduced
@see	Reference to another class/method
@deprecated	Marks as deprecated

Generating Javadoc

javadoc -d docs src/BankAccount.java

This generates HTML documentation in the docs/ folder — the same kind of documentation you see on docs.oracle.com.

---

When to Comment

✅ Good Comments

// Convert Celsius to Fahrenheit using the standard formula
double fahrenheit = (celsius * 9.0 / 5.0) + 32;

// Retry up to 3 times because the API is flaky
for (int attempt = 0; attempt < 3; attempt++) { ... }

// TODO: Replace with database lookup once DB is ready
String name = "hardcoded";

// FIXME: This breaks for negative numbers
int result = sqrt(input);

❌ Bad Comments

int age = 25;  // set age to 25  ← obvious, adds no value

// increment i
i++;  ← the code already says this

// This method does stuff
public void process() { ... }  ← vague and useless

---

The Best Comment Is No Comment

Write self-documenting code so comments become unnecessary:

// Bad: needs a comment to explain
int d; // elapsed time in days

// Good: the name explains itself
int elapsedTimeInDays;

// Bad
if (status == 2) { ... }  // 2 means active

// Good
if (status == Status.ACTIVE) { ... }

Rule of thumb: If you feel the need to write a comment explaining what code does, consider renaming variables or extracting a method instead. Save comments for explaining why.

---

Special Comment Tags

TODO

// TODO: Add input validation

FIXME

// FIXME: Division by zero when quantity is 0

HACK

// HACK: Workaround for library bug #1234

Most IDEs (IntelliJ, VS Code) can list all TODO/FIXME comments across your project.

---

Commenting Out Code

During debugging, you might temporarily disable code:

// System.out.println("Debug: value = " + x);

Don’t leave commented-out code in production. Use version control (Git) to track deleted code instead.

---

Quick Exercises

1. Add a Javadoc comment to a calculateArea(double radius) method.
2. Find three comments in your code that explain “what” and rewrite the code so the comment is unnecessary.
3. Add TODO comments for features you plan to add later.

---

Summary

Type	Syntax	Purpose
Single-line	//	Quick inline notes
Multi-line	/* */	Longer explanations
Javadoc	/** */	API documentation

Best practices:

• Comment why, not what
• Prefer self-documenting code
• Use TODO/FIXME for tracking
• Don’t leave commented-out code

---

What’s Next?

Now let’s learn about boolean expressions — the foundation of all decision-making in Java: Boolean Expressions.