Java Comments – How to Document Your Java Code Like a Pro

Introduction – Why Java Comments Matter

Writing code that works is important. But writing code that others can understand — that’s professional.

Java comments help you explain, document, and disable parts of your code without affecting program execution. Whether you’re working solo or on a large team, comments make your code easier to maintain, debug, and extend.

In this article, you’ll learn:

• The three types of Java comments
• How and when to use each type
• Best practices for clean, readable documentation
• How comments are used in professional Java projects

What Are Comments in Java?

Comments are ignored by the Java compiler. They’re written for humans — not machines.

Java supports three types of comments:

1. Single-Line Comments – //

This is the most commonly used comment type.

public class HelloWorld {
    public static void main(String[] args) {
        // This prints a greeting to the console
        System.out.println("Hello, World!");
    }
}

When to Use:

• Quick explanations
• Disabling a single line during debugging
• Inline code documentation

2. Multi-Line Comments – /* ... */

Use these when you need to explain a block of code or logic.

/*
  This program prints the sum of two numbers.
  It uses integer variables and basic arithmetic.
*/
public class SumExample {
    public static void main(String[] args) {
        int a = 5;
        int b = 3;
        System.out.println(a + b);
    }
}

Tip: Great for temporary blocks of code you’re testing or skipping.

3. Documentation Comments (Javadoc) – /** ... */

Used to generate API documentation using the javadoc tool.

/**
 * This class performs basic math operations.
 * @author John
 * @version 1.0
 */
public class Calculator {

    /**
     * Adds two integers and returns the result.
     * @param a first number
     * @param b second number
     * @return sum of a and b
     */
    public int add(int a, int b) {
        return a + b;
    }
}

Features:

• Uses tags like @param, @return, @author
• Automatically generates HTML documentation
• Ideal for public libraries and APIs

Note: Javadoc is a Java standard for creating developer-friendly documentation.

Best Practices for Writing Java Comments

Avoid These Commenting Mistakes

int a = 5; // setting a to 5 (redundant)

Redundant comments waste time and clutter your code.

Instead, write:

int maxLoginAttempts = 5; // Maximum allowed login retries

Tip: Use meaningful variable names and write fewer—but better—comments.

Summary – Java Comments Essentials

Java comments let you communicate intentions, document logic, and build cleaner projects.

• Use // for simple inline or line-based notes
• Use /* ... */ for longer blocks or temporary disabling
• Use /** ... */ for generating documentation with javadoc

FAQs – Java Comments

Will comments increase program size?

No. Comments are ignored by the compiler and do not appear in the final bytecode.

How do I generate Java documentation from comments?

Use the javadoc tool on your .java files. It reads documentation comments and produces HTML.

javadoc MyClass.java

Can I comment out multiple lines quickly?

Yes. In most IDEs, select lines and press:

• Ctrl + / (Windows)
• Cmd + / (macOS)

Are comments required in Java code?

No, but they are highly recommended for readability and collaboration.