• +91-9142290450

  • Hajipur, Bihar, 844101

☰
❮
❯

Java Comments

← Previous Next →

Comments are one of the most underrated yet essential parts of any programming language. They don’t affect how the program runs, but they play a huge role in explaining what the code does. When you revisit your code after weeks or when someone else reads it, comments help everyone understand its logic and purpose quickly.

In Java, comments are ignored by the compiler. They exist purely to make your program more readable, organized, and maintainable. In this tutorial, you’ll learn about different types of comments in Java, how to use them effectively, and why they are important in professional coding.

What Are Comments in Java?

A comment in Java is a piece of text inserted inside your code that is not executed by the Java compiler. Its only purpose is to describe what the code is doing.

Think of comments as “notes for humans.” They explain why something is written a certain way or what a particular block of code is meant to achieve.

For example:

// This line prints a message on the screen
System.out.println("Hello, Java!");

Here, the comment helps anyone reading the program understand what the line below it does.

Types of Comments in Java

Java supports three main types of comments:

  1. Single-line comments

  2. Multi-line comments

  3. Documentation comments

Each serves a different purpose depending on the situation.

1. Single-line Comments

A single-line comment starts with two forward slashes //.
Everything written after // on that line is treated as a comment and ignored by the compiler.

Syntax:

// This is a single-line comment

Example:

class Hello {
    public static void main(String[] args) {
        // Print greeting message
        System.out.println("Welcome to Java Comments!");
    }
}

Output:

Welcome to Java Comments!

Here, the text after // is not part of the code; it only helps explain it.

Single-line comments are ideal for short notes or explaining a single line of code.

2. Multi-line Comments

When you need to write longer explanations or temporarily disable a block of code, multi-line comments are more useful.

A multi-line comment begins with /* and ends with */. Everything between these symbols is ignored by the compiler.

Syntax:

/* This is a
   multi-line comment */

Example:

class Example {
    public static void main(String[] args) {
        /* The following code prints two lines of text
           It demonstrates the use of multi-line comments */
        System.out.println("Java is simple.");
        System.out.println("Java is powerful.");
    }
}

Output:

Java is simple.
Java is powerful.

You can also use multi-line comments to temporarily disable code while debugging:

/* System.out.println("This line won't run."); */
System.out.println("This line will run.");

This is called commenting out code, which helps in testing specific parts of your program.

3. Documentation Comments

Documentation comments are a special kind of comment used to create HTML documentation for your Java programs.

They start with /** and end with */. The text inside these comments can be processed by a tool called Javadoc, which generates detailed documentation automatically.

Syntax:

/**
 * This is a documentation comment.
 * It can be converted into HTML documentation.
 */

Example:

/**
 * The Student class stores information about a student.
 * It contains the student's name and marks.
 */
class Student {
    String name;
    int marks;

    /**
     * Displays student details
     */
    void showDetails() {
        System.out.println("Name: " + name);
        System.out.println("Marks: " + marks);
    }
}

To generate documentation from these comments, you can run the Javadoc tool in your terminal:

javadoc Student.java

This creates an HTML file that documents the class and its methods. Documentation comments are mainly used in professional and open-source projects.

Why Use Comments in Java?

Comments serve several important purposes in Java programming:

  1. Improves Readability:
    Code becomes easier to understand when important logic or steps are explained.

  2. Helps During Debugging:
    You can comment out specific lines of code to test smaller parts of a program.

  3. Acts as a Reminder:
    When you revisit your project later, comments help recall why certain decisions were made.

  4. Collaboration:
    In team projects, comments make it easier for multiple developers to understand each other’s code.

  5. Documentation:
    Especially in larger programs, documentation comments can be turned into professional API documentation.

Best Practices for Writing Comments

Writing comments is an art. Over-commenting or writing vague comments can make code harder to read. Follow these practices to write useful and professional comments:

  1. Be Clear and Brief
    Comments should explain the “why,” not restate the obvious.
    Example:

    // Calculate area of a circle
double area = Math.PI * radius * radius;

  2. Keep Comments Updated
    Outdated comments can confuse readers. Always update or remove incorrect comments.

  3. Avoid Commenting Every Line
    Only add comments where the logic might not be immediately clear.

  4. Use Proper Grammar and Formatting
    A clean, well-written comment is easier to read.

  5. Use Documentation Comments for Methods and Classes
    For public APIs, always describe purpose, parameters, and return values.

  6. Don’t Explain Obvious Code
    Avoid comments like:

    int x = 5; // Declare integer variable

    This adds no real value.

Example Program with Different Comments

/**
 * This program demonstrates different types of comments in Java.
 */
class CommentDemo {
    public static void main(String[] args) {
        // Single-line comment: Printing greeting message
        System.out.println("Welcome!");

        /* Multi-line comment:
           The following code prints multiple lines of output */
        System.out.println("Learning Java is fun!");
        System.out.println("Practice helps improve coding skills.");

        /**
         * Documentation comment:
         * The next line prints a farewell message.
         */
        System.out.println("Goodbye!");
    }
}

Output:

Welcome!
Learning Java is fun!
Practice helps improve coding skills.
Goodbye!

This program combines all three comment types in one place.

When Not to Use Comments

There are a few cases where comments can do more harm than good:

  • When they simply repeat what the code already says.

  • When they become outdated after code changes.

  • When comments are used instead of writing clear code.

If your code is self-explanatory, you don’t need extra comments. Clean code often speaks for itself.

Summary of the Tutorial

In this chapter, you learned about Java comments and their three types: single-line, multi-line, and documentation comments. Comments make code easier to read, maintain, and share, especially in larger projects. Knowing how and when to use comments effectively is an important part of writing clean and professional Java code.

In the next tutorial, you can move on to Java Variables, where you’ll learn how to store and manipulate data in Java programs.

Practice Questions

1. What is the main purpose of comments in a Java program?

2. Do comments in Java affect the execution or performance of a program? Explain why or why not.

3. What are the three types of comments supported in Java?

4. How is a single-line comment written in Java? Give an example.

5. When should you use a multi-line comment instead of a single-line comment?

6. What is the purpose of documentation comments in Java, and how are they different from other comment types?

7. What tool is used to generate HTML documentation from documentation comments in Java?

8. What does it mean to “comment out” a line of code, and why is it done?

9. List at least three best practices to follow when writing comments in Java.

10. Why can outdated comments be harmful in a program, and how can you avoid that issue?

← Previous Next →

Try a Short Quiz.

coding learning websites codepractice

No quizzes available.

Java

online coding class codepractice

Java Basics

Java Variables & Data Types

Java Control Flow

Java Arrays

Java Methods

Java Classes & Objects

OOP Principles

Java Utilities

Error Handling

Collections Framework

Java File Handling

Advanced Java

codepractice logo
Login
Go Back Top