Java Comments and Javadoc

Why comments matter

You write clever code today. Three months later you open it and think, “what was I doing here?” That is the pain comments solve.

A comment is a note for humans, not the computer. Java skips right over it, so it never runs.

• Code says what. Comments say why, which the code alone cannot show.
• The next reader is often you. A short note now saves a confused hour later.
• Teams share files. Comments let people understand your work without asking you.

Java gives you three kinds.

Single-line comments

The single-line comment starts with two slashes, //. Everything from there to the end of that line is ignored.

Here it is on its own line and at the end of a line of code.

// This whole line is a note for humans.
int score = 90; // You can also add a note after code, like this.

• It stops at the end of the line. The next line is normal code again.
• It works in two spots: on its own line, or at the end of a code line.
• It is the most common kind. Reach for it for any short note.

Multi-line comments

When a note runs past one line, use the multi-line comment. It starts with /* and ends with */. Everything between is ignored, even across many lines.

Here it explains the block of code below it.

/*
   This program works out the final price.
   It adds tax, then takes off any discount.
   Riya asked for this calculation last week.
*/
double finalPrice = (basePrice * 1.1) - discount;

• It spans as many lines as you like. Open with /*, close with */.
• The * people add on each line is just for looks. Java does not need it.
• Forget the closing */ and Java treats the rest of your file as one big comment, so your code stops working.

Documentation comments (Javadoc)

The documentation comment looks like a multi-line comment but opens with /**, two stars instead of one. It is called a Javadoc comment, and it is more than a note.

You place it right above a class or method to describe what it does.

/**
 * Adds two whole numbers and gives back the total.
 */
public int add(int a, int b) {
    return a + b;
}

What makes it different from a normal comment:

• It describes the class or method right below it, so the reader sees the description first.
• A tool can read it. Java ships with a program called javadoc that turns these comments into a neat HTML page.
• The two-star /** opening tells javadoc “this is documentation, include it”.

So a Javadoc comment can grow up into a real web page. Now the tags that make it powerful.

Javadoc tags

A tag is a special word starting with @. It marks one piece of information in a standard way, so javadoc knows exactly what it is. The common ones:

• @param describes one input. Write one line per input.
• @return describes what the method gives back.
• @author names who wrote the code. It usually goes above a class.

Here is a fully documented method.

/**
 * Works out the area of a rectangle.
 *
 * @param width  the width of the rectangle
 * @param height the height of the rectangle
 * @return the area, found by multiplying width and height
 * @author Alex
 */
public int area(int width, int height) {
    return width * height;
}

• The first sentence says what the method does.
• Each @param explains one input.
• @return says what comes back, and @author credits the writer.

Now run the javadoc tool on your file from the command line.

javadoc Rectangle.java

It reads your /** */ comments, picks out the tags, and builds an HTML page showing each method, its inputs, and its return value.

Good comments vs bad comments

Not all comments help. The golden rule: explain why, not what. The code already shows what it does, so a comment that repeats it in English is just noise.

Look at this weak comment.

// ❌ Bad: this just repeats what the code plainly says
i = i + 1; // add one to i

Anyone can see it adds one to i. Now a comment that earns its place.

// ✅ Good: explains the reason, which the code cannot show
i = i + 1; // skip the header row before reading the data

You could never guess that reason from the code alone. That is the whole point.

• Say why, not what. The reader can already see what the line does.
• Do not state the obvious. A // the main method note above main wastes time.
• Let clear code speak. A well-named variable like discountedPrice often removes the need for a comment.

Commenting out code

To make Java skip a line without deleting it, put // in front of it. This is called commenting out code, and it is handy while testing.

Both styles turn code off below.

System.out.println("This line runs.");
// System.out.println("This line is switched off for now.");

/*
System.out.println("These two lines");
System.out.println("are both switched off.");
*/

Remove the slashes later to switch the line back on. One warning: do not leave large blocks of dead, commented-out code in your final work. It clutters the file and confuses readers. Bring it back or delete it for good.

Common Mistakes

Two comment habits cause real trouble.

First, over-commenting. Adding a comment to every line, even obvious ones, buries the few useful comments in noise.

// ❌ Wrong: a comment on every obvious line
int age = 25; // set age to 25
age = age + 1; // add one to age
System.out.println(age); // print age

// ✅ Right: let clear code speak, comment only where it helps
int age = 25;
age = age + 1; // a birthday just passed, so bump the age
System.out.println(age);

Second, the stale comment. It was true once, but the code changed and nobody updated the note. Now it lies, which is worse than no comment at all.

// ❌ Wrong: the comment says 10% but the code uses 20%
// Apply a 10% discount
double price = basePrice * 0.80;

// ✅ Right: the comment matches what the code actually does
// Apply a 20% discount
double price = basePrice * 0.80;

When you change code, check the comment beside it. A wrong comment sends the next reader down the wrong path.

Best Practices

• Explain why, not what. Save comments for the reason, not a replay of the line.
• Keep comments up to date. A stale comment is worse than none.
• Prefer clear names over comments. A good name often makes a comment unnecessary.
• Use Javadoc for shared code, with @param and @return tags.
• Do not leave dead code commented out. Bring it back or delete it.

What You’ve Learned

Now you can write notes that help the next reader. Let’s recap.

• ✅ A comment is a note for humans that Java ignores. It never runs.
• ✅ Single-line comments start with // and cover the rest of that line.
• ✅ Multi-line comments sit between /* and */ and can span many lines.
• ✅ Javadoc comments start with /** and describe a class or method.
• ✅ Javadoc tags like @param, @return, and @author mark information in a standard way, and the javadoc tool turns them into HTML docs.
• ✅ Good comments explain why, not what, and never state the obvious.
• ✅ You can comment out code to switch it off while testing.

What’s Next?

You can now write clear notes and even proper documentation for your code. Next let’s see what actually happens when you turn your Java file into a running program, step by step.

Java Compilation and Execution Process