Java Comments: Single-Line, Multi-Line & Documentation Comments Explained

Comments are notes written inside source code to explain what the program is doing. Java completely ignores comments during program execution, which makes them useful for documenting logic without changing how the application behaves.

A well-written comment should answer a question that the code itself may not answer easily—especially why a particular decision was made. Good developers use comments to provide context, not to repeat obvious code.

Why Comments Exist

Imagine opening a Java project six months after writing it. The syntax may still be familiar, but a complicated calculation or unusual business rule may no longer be obvious. A useful comment can preserve the reasoning behind that code.

// Calculate the final price after applying the discount
double finalPrice = price - (price * discount / 100);

The code explains how the calculation works, while the comment explains its purpose. That distinction is important in professional software development.

Types of Comments in Java

Java provides three common forms of comments: single-line comments, multi-line comments, and documentation comments.

Type	Syntax	Typical Use
Single-line	// comment	Short explanations
Multi-line	/* comment */	Longer explanations or temporarily disabling code
Documentation	/** comment */	Generating API documentation

Single-Line Comments

A single-line comment begins with two forward slashes: //. Everything after these symbols on that line is treated as a comment.

// Store the user's age
int age = 25;

The compiler ignores the comment and processes only the Java statement.

A single-line comment can also appear after executable code.

int maxLoginAttempts = 3; // Maximum allowed attempts

This style is useful when the explanation is short enough to remain readable on the same line.

Multi-Line Comments

A multi-line comment begins with /* and ends with */. It can span multiple lines.

/*
 * Calculate the employee bonus.
 * The bonus depends on the annual performance score.
 */
double bonus = salary * bonusRate;

Multi-line comments are useful when a concept needs more explanation than a single line can comfortably provide.

Commenting Out Code

Developers sometimes temporarily disable a piece of code by commenting it out.

int price = 500;
// int discount = 20;
System.out.println(price);

The commented statement remains visible but is not compiled as executable Java code.

Professional tip: Commenting out code can be useful during short debugging experiments, but avoid leaving large blocks of dead code in a production project. Version control systems already preserve previous versions of your code.

Documentation Comments

Documentation comments begin with /** and end with */. They are designed to describe classes, methods, constructors, and other program elements.

/**
 * Calculates the total price after applying a discount.
 *
 * @param price original product price
 * @param discount discount percentage
 * @return final price after discount
 */
double calculatePrice(double price, double discount) {
    return price - (price * discount / 100);
}

Documentation comments can be processed by Java documentation tools to create structured API documentation. This becomes particularly valuable when developing libraries, frameworks, and public APIs.

Comments Do Not Affect Program Execution

Consider this program:

public class Demo {
    public static void main(String[] args) {
        // Print a welcome message
        System.out.println("Welcome to Java");
    }
}

The comment does not produce any output. The program prints only the message supplied to println(). Comments exist for humans reading and maintaining the source code, not for the Java runtime.

Comments vs Code

Code	Comment
Processed by the compiler	Ignored by the compiler
Controls program behavior	Provides explanation or documentation
Must follow Java syntax	Can contain ordinary descriptive text
Executed when applicable	Never executed

Good Comments vs Bad Comments

Not every comment improves code. A comment that merely repeats the statement adds noise.

// Add 1 to count
count = count + 1;

The code is already clear enough to explain what it does. A better comment explains the reason when the reason is not obvious.

// Keep the first attempt reserved for account recovery.
count = count + 1;

The second comment provides useful context that cannot be understood simply by reading the statement.

Remember: Good comments explain why; clean code should usually explain what and how.

Common Beginner Mistakes

• Forgetting to close a multi-line comment with */.
• Writing comments that describe obvious statements.
• Leaving outdated comments after changing the code.
• Using comments as a replacement for meaningful variable and method names.
• Leaving large amounts of commented-out code in production files.
• Writing documentation comments that no longer match the actual method behavior.

Best Practices

• Write comments when they provide useful context.
• Keep comments short and precise whenever possible.
• Update comments whenever the related code changes.
• Prefer meaningful names over excessive comments.
• Use documentation comments for public APIs and reusable components.
• Avoid explaining code that is already obvious.

Interview Insights

Question	Key Point
What is a comment?	Text in source code that is ignored by the compiler and used for explanation or documentation.
How do you write a single-line comment?	Begin the comment with //.
How do you write a multi-line comment?	Enclose the text between /* and */.
What is a documentation comment?	A /** ... */ comment used to document program elements and support API documentation.
Do comments affect program execution?	No. Comments are not executed by the Java runtime.
Should every line of code have a comment?	No. Comments should add meaningful context rather than duplicate obvious code.

Quick Revision

Comment Type	Syntax	Best Use
Single-line	//	Short explanations
Multi-line	/* ... */	Longer explanations
Documentation	/** ... */	API and program documentation

Comments are a small feature with a surprisingly important role in professional Java development. They should not be used to make poorly written code understandable; instead, they should capture important reasoning, assumptions, and documentation that the code cannot express clearly by itself. As your programs become larger, learning when to comment—and when not to comment—will become just as valuable as knowing how to write the code.