Comments in Java

Analogy categoryAnalogies

1. Introduction

Comments in Java are lines of text in source code that are ignored by the compiler and are used to explain what the code does, making programs easier to read, understand, and maintain. Comments have no effect on program execution or performance.

🏏

Cricket analogy: A coach's handwritten notes in the margin of a game plan explaining why a field setting was chosen don't affect how the match is actually played, just as Java comments explain code without affecting how it runs.

Java supports three types of comments: single-line comments, multi-line (block) comments, and Javadoc comments, which are used to automatically generate API documentation.

🏏

Cricket analogy: Cricket commentary comes in quick one-ball remarks, extended pitch-report analysis, and formal post-match official reports for the record books, just as Java offers single-line comments, block comments, and Javadoc for generated documentation.

2. Syntax

java

// This is a single-line comment

/*
 * This is a
 * multi-line (block) comment
 */

/**
 * This is a Javadoc comment.
 * @param name the name to greet
 * @return a greeting message
 */
public String greet(String name) {
    return "Hello, " + name;
}

3. Explanation

A single-line comment begins with // and continues to the end of that line; it is typically used for brief explanations next to a line of code. A multi-line (or block) comment starts with /* and ends with */, and can span multiple lines; it is useful for longer explanations or for temporarily disabling a block of code during debugging.

🏏

Cricket analogy: A quick shout of 'well bowled!' from the boundary is like a // comment, ending the moment the ball stops, while a full radio commentary segment spanning several overs, like when rain delays play, resembles a /* */ block comment covering multiple lines.

A Javadoc comment starts with /** (a slash followed by two asterisks) and ends with */. It is placed immediately before a class, method, or field declaration and can include special tags like @param, @return, @throws, and @author. The javadoc tool can process these comments to automatically generate HTML API documentation, which is why classes like the Java standard library have well-documented online references.

🏏

Cricket analogy: A player's official ICC profile page, placed right before their stats with structured fields like role, batting average, and bowling style, mirrors a Javadoc comment placed before a class with @param-like structured tags generating a public reference page.

Best practice: comments should explain WHY code does something, not restate WHAT the code obviously does. Over-commenting obvious code (e.g., // increment i by 1 above i++;) adds noise rather than value.

Exam trap: block comments (/* */) cannot be nested in Java. Writing /* outer /* inner */ still ends */ */ causes a compile error because the first */ closes the entire block comment, leaving a stray */ as invalid code.

4. Example

java

/**
 * CommentsDemo shows the three comment types in Java.
 * @author SkillVeris
 */
public class CommentsDemo {
    public static void main(String[] args) {
        // single-line comment: print a greeting
        System.out.println("Hello, Java!");

        /*
         * Multi-line comment:
         * The next line calculates a sum.
         */
        int sum = 5 + 10;
        System.out.println("Sum: " + sum);
    }
}

5. Output

text

Hello, Java!
Sum: 15

6. Key Takeaways

Java supports single-line (//), multi-line (/* */), and Javadoc (/** */) comments.
Comments are ignored by the compiler and do not affect program execution.
Javadoc comments use tags like @param, @return, and @author to generate HTML documentation.
Block comments (/* */) cannot be nested in Java.
Good comments explain intent and reasoning, not obvious syntax.