Java Comments

In computer programming, comments are a portion of the program that are completely ignored by Java compilers. They are mainly used to help programmers to understand the code.

// declare and initialize two variables
int a = 1;
int b = 3;

// print the output
System.out.println("This is output");

Types of Comments in Java

In Java, there are three types of comments:

1. Single-line comment
2. Multi-line comment
3. Documentation comment (Javadoc)

1. Single-line Comment

A single-line comment starts and ends in the same line. To write a single-line comment, we can use the // symbol.

// "Hello, World!" program example

class Main {
    public static void main(String[] args) {
        // prints "Hello, World!"
        System.out.println("Hello, World!");
    }
}

The Java compiler ignores everything from // to the end of line.

2. Multi-line Comment

When we want to write comments in multiple lines, we can use the multi-line comment. To write multi-line comments, we can use the /*....*/ symbol.

/* This is an example of  multi-line comment.
 * The program prints "Hello, World!" to the standard output.
 */

class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello, World!");
    }
}

3. Documentation Comment (Javadoc)

Documentation comments are used to create API documentation. They start with /** and end with */.

/**
 * This class represents a Student.
 * @author Javapedia
 * @version 1.0
 */
public class Student {
    /**
     * Calculates the grade based on marks.
     * @param marks The marks obtained by the student.
     * @return The grade (A, B, C, etc.)
     */
    public char calculateGrade(int marks) {
        // logic
        return 'A';
    }
}

Use Comments the Right Way

One thing you should always consider that comments shouldn't be the substitute for a way to explain poorly written code in English. You should always write well structured and self explaining code. And, then use comments.

Bad Comment:

// This variable stores the age
int a = 10;

Good Code (No comment needed):

int age = 10;

Good Comment:

// We use a binary search here because the list is already sorted
// and performance is critical for this large dataset.
int index = binarySearch(list, target);

Key Takeaways

• Single-line: Starts with //. Everything after is ignored.
• Multi-line: Starts with /* and ends with */. Can span multiple lines.
• Javadoc: Starts with /** and ends with */. Used for generating API documentation.
• Purpose: Use comments to explain why you did something, not what the code is doing (unless it's complex).

Common Pitfalls

[!WARNING] Over-commenting: Don't comment obvious things like int a = 5; // declaring integer a. It clutters the code.

[!WARNING] Nesting: You cannot nest multi-line comments inside other multi-line comments. /* /* */ */ will cause an error.

Challenge