Java — Comments

Why comments exist

Comments are notes for humans. The compiler ignores them entirely, but other developers (including future you) rely on them to understand why code does what it does.

Good comments don't explain what — the code already shows that. They explain why, what assumption, or what edge case is being handled.

Single-line comments

Two forward slashes start a comment that runs to the end of the line:

// Calculate the discount price
double discounted = price * 0.9;

Use single-line comments for short explanations directly above or beside a statement. Keep them brief — one line is usually enough.

Multi-line comments

Wrap longer explanations between /* and */:

/*
 * This function validates the user's input.
 * It rejects empty strings, strings shorter
 * than 8 characters, and strings containing
 * special characters.
 */
public static boolean isValid(String input) {
    // ...
}

Multi-line comments span as many lines as you need. The leading * on each line is convention, not requirement — it keeps the block visually aligned.

Documentation comments

Three slashes /** start a Javadoc comment. These describe public APIs — classes, methods, and fields that other developers will use:

/**
 * Calculates the area of a rectangle.
 *
 * @param width  the width in centimeters
 * @param height the height in centimeters
 * @return the area in square centimeters
 */
public static double area(double width, double height) {
    return width * height;
}

Tools like javadoc read these comments and generate HTML reference pages. Every library you'll ever use was documented this way. Writing Javadoc for your own public methods is a professional habit worth building early.

Javadoc tags

Tag	Purpose
@param	Describes a parameter
@return	Describes the return value
@throws	Documents exceptions that can occur
@see	Points to related methods or classes
@since	Notes which version introduced the feature
@deprecated	Warns that the method should not be used

/**
 * Reads a student record from the database.
 *
 * @param id the unique student identifier
 * @return the Student object, or null if not found
 * @throws SQLException if the database connection fails
 * @see #saveStudent(Student)
 * @deprecated Use {@link #fetchStudent(long)} instead.
 */
public static Student getStudent(long id) throws SQLException {
    // ...
}

These tags become clickable links in generated HTML docs. Even if you never generate docs, the structured format makes your comments consistent and scannable.

When to comment

Do comment when:

• The why isn't obvious from the code alone
• You're working around a known bug or limitation
• A non-obvious algorithm or business rule is implemented
• You're marking a TODO or FIXME for later

Don't comment when:

• The comment restates what the code does (// increment i by one above i++)
• The code is clear enough on its own
• Comments would duplicate the function's Javadoc
• The comment is outdated — wrong comments are worse than no comments

TODO and FIXME markers

Many IDEs recognize TODO and FIXME as special keywords and highlight them:

// TODO: add input validation for negative numbers
public static double divide(double a, double b) {
    return a / b;  // FIXME: crashes when b is zero
}

TODO marks planned work. FIXME marks known broken behavior. Both are signposts — use them to track tech debt, then resolve them before shipping.

Commenting out code

Developers sometimes comment out code instead of deleting it:

// int result = oldMethod(input);
int result = newMethod(input);

This is tempting but harmful. Version control (Git) already preserves every past version. Commented-out code rots — it stops working but nobody removes it. Delete it. Git remembers.

If you need to keep dead code temporarily during debugging, add a clear marker:

// DEBUG: remove before merge
// oldMethod(input);

Block commenting for quick tests

When experimenting, you can quickly disable a block of code:

/*
System.out.println("step 1");
System.out.println("step 2");
System.out.println("step 3");
*/
System.out.println("only this runs");

Use this sparingly. A proper debugging approach — breakpoints or logging — is cleaner than commenting out chunks.

Comments and readability

Well-placed comments reduce the time a new developer needs to understand your code. But they're not a substitute for clear naming and simple logic.

The best code needs very few comments because it reads like a story:

boolean isEligible = age >= 18 && hasValidId;
if (isEligible) {
    grantAccess(user);
}

No comment needed — the variable name and condition say everything.

Mini Practice

1. Write a method that calculates BMI — add a Javadoc comment describing parameters and return value
2. Find a piece of code in a project and add a // why comment explaining a non-obvious decision
3. Search a codebase for TODO or FIXME — understand what they track
4. Write a method, then remove all comments — see if the code is still readable without them
5. Add a documentation comment to a method with @param, @return, and @throws

Next: storing data with variables →