Comments in Java

A comment is a note written inside Java code for a person to read. Java ignores comments when it compiles and runs the program. They are useful when the code needs an explanation that a clear variable name cannot give.

For example, a calculation may be simple, but the business rule behind it may not be obvious. A comment can explain that rule.

Why comments are useful

Good code should already use clear names such as discountPercentage and totalMarks. Comments are not a replacement for clear names. Use them to explain a decision, warning, rule, or reason.

Run this example to see its output.

The comment does not repeat the code. The code already shows that Java compares score with 40. The comment explains why the number 40 is important. If the pass mark changes later, the programmer knows both the code and rule to review.

Three comment styles

Java gives you three ways to write comments. Choose the shortest style that clearly explains the note.

Run this example to see its output.

In the example, // explains one line inside the loop. The /* ... */ comment explains why a cast happens before division. The /** ... */ comment describes what the average method expects and does.

Explain why, not what

Before writing a comment, ask: can the code already explain this by using a better name? If yes, improve the name instead of adding a comment.

Run this example to see its output.

totalMarks += mark is already understandable, so “add mark to total” adds no useful information. The second comment explains something the code cannot show by itself: validation happened at an earlier stage.

Use comments for questions such as:

• Why is this value fixed at 40?
• Why is a special case handled here?
• Why is an external library used?
• What must a person remember before changing this code?

Javadoc: comments for people who call your method

Javadoc is a special comment style that can become documentation for a public class or method. Use it when another programmer needs to know what method to call, what values to provide, and what result to expect.

Run this example to see its output.

@param describes an input the method receives. @return describes the result the method gives back. You do not need Javadoc for every small practice program, but it becomes valuable when you write reusable classes and methods.

Do not keep old code as a comment

You may be tempted to do this when changing a program:

Delete old code when it is no longer needed. Git keeps the previous version, so commented-out code only makes the current program harder to read. Keep a comment only when the reason for a current line needs to stay visible.

Common comment mistakes

• Commenting every obvious line makes the program noisy and hides the useful notes.
• Leaving old, broken code commented out makes it unclear which code is current.
• Writing a comment that no longer matches the code is worse than writing no comment; update it when the rule changes.

When a comment seems necessary only because a variable or method has a vague name, rename the code first. Keep the comment for the business rule or unusual decision that the name cannot express.

Try it yourself

Create a class named DiscountCheck.

1. Store a price and a discount percentage.
2. Calculate the discounted price.
3. Add one useful comment that explains the discount rule.
4. Do not add comments that only repeat obvious code.

One working answer

Run this example to see its output.

Change the discount percentage and run the code. Then decide whether your own comment explains a real rule or merely repeats what Java already says.