Comments in Java

Introduction

Comments are an essential part of writing clean, maintainable code. They allow developers to leave notes, explain complex logic, and generate API documentation. In Java, comments are ignored by the compiler (javac), meaning they have zero impact on the runtime performance or bytecode size of the application.

This guide covers the three types of comments in Java, how to use them effectively, and the internal tooling that leverages them.

Types of Comments

Java supports three primary types of comments:

1. Single-Line Comments

Single-line comments start with two forward slashes (//). Everything following the // on that line is ignored by the compiler.

public class SingleLineExample {
    public static void main(String[] args) {
        // This is a single-line comment
        int count = 10; // Inline comments are also supported
    }
}

2. Multi-Line Comments

Multi-line comments (also called block comments) start with /* and end with */. They are useful for commenting out large blocks of code or writing longer explanations.

public class MultiLineExample {
    /*
     * This is a multi-line comment.
     * It can span multiple lines.
     * Often used for disabling blocks of code during debugging.
     */
    public void performAction() {
        /* int x = 5;
           int y = 10;
           System.out.println(x + y); */
    }
}

3. Javadoc Comments

Javadoc comments start with /** and end with */. They are specially parsed by the javadoc tool to automatically generate HTML-based API documentation. Javadoc comments typically appear immediately before class, interface, method, or field declarations.

/**
 * Represents a simple calculator.
 * 
 * @author Java Developer
 * @version 1.0
 */
public class Calculator {
    
    /**
     * Adds two integers.
     * 
     * @param a The first integer.
     * @param b The second integer.
     * @return The sum of a and b.
     */
    public int add(int a, int b) {
        return a + b;
    }
}

Javadoc Tags and Tooling

When using Javadoc comments, specific tags help structure the generated documentation:

• @param: Describes a method parameter.
• @return: Describes the return value.
• @throws / @exception: Documents exceptions that a method might throw.
• @see: Provides a cross-reference to another class or method.
• @since: Indicates the version when the feature was added.
• @deprecated: Marks an API as obsolete and advises against its use.

To generate the documentation, you can run the javadoc command from the terminal:

javadoc -d doc Calculator.java

This generates a set of HTML files in the doc directory.

Best Practices

1. Don't State the Obvious

Avoid writing comments that merely repeat what the code does. The code should be self-documenting whenever possible.

Bad:

int count = 0; // Set count to 0

Good:

// Initialize the retry counter for the network request
int count = 0; 

2. Explain "Why", Not "What"

Good comments explain the reasoning behind a specific decision, especially if the logic is non-intuitive or works around a known bug.

// Using a synchronized block here instead of ConcurrentHashMap
// because we need to perform compound atomic operations safely.
synchronized (lock) {
    // ...
}

3. Keep Comments Updated

Outdated comments are worse than no comments at all. When you modify code, always ensure the surrounding comments and Javadoc are updated to reflect the new behavior.

4. Use TODOs Responsibly

When leaving a TODO comment for future work, include a date, an issue tracker ticket, or a name so it doesn't get lost.

// TODO(JIRA-1234): Refactor this method to use the new Date/Time API once we drop Java 7 support.

Summary

• Java provides single-line (//), multi-line (/* */), and Javadoc (/** */) comments.
• Comments are completely stripped away during the compilation process.
• Javadoc comments are extremely powerful for generating standard API documentation.
• Strive to write expressive, self-documenting code, and use comments to explain the why rather than the what.