Previous
Written by: rJTutorial Team | Last Updated:

Java Comments

Java comments are non-executable statements used for documentation and explanation purposes. While the Java compiler completely ignores these lines, they are arguably one of the most important parts of your codebase. They serve as "notes to self" and a roadmap for other developers, helping anyone reading the code understand the logic, intent, and complexity behind the instructions.

Developer Tip: Use comments to explain the why behind your code, not just the what. Clean code usually tells you what is happening; comments should explain why a specific or unusual approach was taken.

Single-Line Comments:

  • Single-line comments start with //.
  • They extend from the // marker to the end of the line and are ignored by the compiler.
  • These are perfect for short descriptions or for "commenting out" a single line of code during debugging to see how the program behaves without it.
Best Practice: Place single-line comments on a new line above the code they describe, rather than at the end of the line, to keep your code width manageable and readable.

Multi-Line Comments:

  • Multi-line comments are enclosed between /* and */.
  • They can span multiple lines and are ignored by the compiler.
  • These are frequently used for detailed explanations of complex algorithms or for adding copyright headers at the top of a source file.
Common Mistake: Forgetting to close a multi-line comment with */. This can cause large chunks of your actual code to be treated as a comment, leading to confusing compiler errors.

Javadoc Comments:

  • Javadoc comments are used to generate professional HTML documentation for Java code using the JDK's javadoc tool.
  • They start with /** and end with */.
  • Javadoc comments can include special tags like @param (to describe method inputs), @return (to describe what a method sends back), and @throws to provide additional information about potential errors.
Watch Out: Javadoc comments are meant for the public API. Avoid using them inside method bodies; stick to single-line or multi-line comments for internal logic.

Example

In a real-world scenario, you might use these comments to explain a business rule or a specific calculation within a class:

/**
 * Represents a simple greeting utility.
 * This class demonstrates the three types of Java comments.
 * 
 * @author rJTutorial Team
 * @version 1.0
 */
public class HelloWorld {

    /**
     * The main entry point of the application.
     * @param args Command-line arguments passed to the program.
     */
    public static void main(String[] args) {
        
        // Define the standard greeting message
        String message = "Hello, World!"; 

        /* 
           The following line prints the message to the console.
           We use System.out.println for standard output.
        */
        System.out.println(message); // This is an inline comment explaining this specific action
    }
}

Summary

Java supports single-line comments (//), multi-line comments (/* */), and Javadoc comments (/** */). Comments are essential for improving code readability, providing explanations, and generating documentation for Java code. By mastering the art of commenting, you ensure that your code remains maintainable and accessible to your teammates—and to yourself when you revisit the project months later.

Best Practice: Keep your comments up to date. An outdated comment that describes logic which has since changed is often worse than no comment at all, as it can mislead other developers.
Previous