Java Comments

A comment is a note that humans read and the compiler ignores. Think of sticky notes on a recipe card. The notes explain a step, but the cook never eats them. Comments help you remember why you wrote a line and help teammates understand your work.

Types of Java Comments

Java offers three kinds of comments. Each kind suits a different job.

Single-Line Comment

Two slashes start a single-line comment. Everything after the slashes on that line becomes a note.

// This line prints a greeting
System.out.println("Hello");

int age = 20; // age of the student

Multi-Line Comment

A slash and star open the comment. A star and slash close it. The text between them can span many lines.

/* This program calculates the total price.
   It adds tax to the item cost.
   Author: Riya */
double total = price + tax;

Documentation Comment

A slash and two stars open a documentation comment. The javadoc tool reads these comments and builds an HTML help page for your code. Place them directly above a class or method.

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

Common Documentation Tags

Tag	Meaning
@param	Describes one method input
@return	Describes the returned value
@author	Names the writer
@deprecated	Marks old code that people should avoid

Diagram: How the Compiler Reads Your File

The compiler scans each line and skips every comment.

Your file                          Compiler sees
-------------------------------    ------------------------
// Set the speed                   (skipped)
int speed = 60;                    int speed = 60;
/* Check the limit */              (skipped)
if (speed > 50) {                  if (speed > 50) {
   System.out.println("Slow");        System.out.println("Slow");
}                                  }

Comment Out Code for Testing

Developers often turn off a line without deleting it. Add two slashes at the start and the line stops running. Remove the slashes to bring it back.

System.out.println("Step 1");
// System.out.println("Step 2");
System.out.println("Step 3");

The program prints Step 1 and Step 3.

Good Comments and Weak Comments

A good comment explains why code exists. A weak comment repeats what the code already says.

// Weak: adds 1 to count
count = count + 1;

// Good: the first record is a header, so skip it
count = count + 1;

Keep each comment short, clear, and up to date. An outdated comment confuses readers more than no comment at all.

Common Mistakes

• Forgetting the closing star and slash on a multi-line comment
• Placing a multi-line comment inside another multi-line comment, which Java does not allow
• Writing comments for every simple line
• Leaving old comments after changing the code

Where Comments Help Most

Explaining Hard Logic

Complex formulas and tricky rules deserve a short note. A reader who sees the note understands the idea in seconds. The same reader would spend minutes decoding the code alone.

Marking Work in Progress

Many teams write TODO in a comment to mark unfinished work. Search tools find every TODO, so nothing slips away.

// TODO: add input checks before saving

Describing a Class

A documentation comment above a class tells new readers what the class does and who owns it. Good descriptions save hours of reading.

Quick Summary

• Two slashes create a single-line comment
• Slash-star and star-slash create a multi-line comment
• Slash-star-star creates a documentation comment for javadoc
• The compiler skips all comments
• Write comments that explain the reason behind the code