Java Comments and Javadoc

In the last lesson you learned about Java program structure. Along the way you met comments for a moment. Now let’s look at them properly.

🤔 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