Comments in Java

Why Comments Matter

Comments are notes for humans that the compiler ignores. They explain why code exists, document tricky logic, and remind the next developer (often yourself) what a block is doing.

Three Comment Styles

1. Single-line comment

// This line is ignored by the compiler
int age = 25; // inline comment after code

2. Multi-line comment

/* Useful for temporary blocks
   or notes that need several lines.
   Everything between the markers is ignored. */
int score = 100;

3. Documentation comment (Javadoc)

/**
 * Calculates the area of a circle.
 *
 * @param radius the radius of the circle
 * @return the area
 */
public double circleArea(double radius) {
    return Math.PI * radius * radius;
}

Javadoc comments can be turned into HTML documentation by running the javadoc tool.

Best Practices

• Explain why, not what. The code already shows what it does.
• Keep comments up to date; a stale comment is worse than none.
• Use Javadoc for public methods that others will use.
• Avoid commenting out long blocks; delete dead code instead.

Key Points

• Three styles: //, /* */, and /** */.
• Javadoc comments generate API documentation.
• Comment the reason, keep it fresh, and let the code speak for itself.