Basic Syntax
Comments
Single-line, multi-line, and Javadoc commenting systems, focusing on auto-generating API documentation.
Interview: Checks knowledge of Javadoc tags, documentation compilation, and writing clean, self-documenting code.
Comments are non-executable statements in a program. They are used to document code logic, explain design decisions, or temporarily disable statements during debugging. Java supports three types of comments: Single-Line, Multi-Line, and Javadoc comments.
Core Idea
Javadoc comments use a specific syntax that can be compiled into structured HTML documentation using the javadoc tool.
Why It Matters
Outdated comments can mislead developers. Code should be self-documenting, using comments only to explain why code was written a certain way.
Interview Lens
Tests how comments interact with annotations, Javadoc tags (like @param), and best practices for writing maintainable code.
The Three Comment Types
- Single-Line Comments (
//): Everything from the//to the end of the line is ignored by the compiler. - Multi-Line Comments (
/* ... */): Everything between the opening and closing markers is ignored. These cannot be nested. - Javadoc Comments (
/** ... */): Positioned directly above classes, methods, or fields. They are read by thejavadoctool to automatically generate HTML API documentation.
Common Javadoc Tags
Javadoc comments use metadata tags to generate structured documentation:
@param name description: Explains a method parameter.@return description: Explains the method's return value.@throws type description: Explains exceptions thrown by the method.@deprecated description: Marks code as obsolete and warns developers not to use it.@see reference: Links to related classes or methods.
Common Pitfalls
- Stale Comments: Code is refactored, but the comments are not updated. Outdated comments can mislead developers and cause bugs.
- Over-Commenting: Writing obvious comments like
// increment x by 1. This clutters code and makes it harder to read.
Best Practices
- Write Self-Documenting Code: Choose clear variable and method names (e.g.
int daysUntilExpiration;) instead of writing cryptic names with explanatory comments (e.g.int d; // days to exp). - Explain the 'Why', Not the 'What': Use comments to explain the business logic or rationale behind complex code, rather than restating what the syntax does.
Interview-Relevant Information
Q1: How do Javadoc comments differ from multi-line comments?
Answer: Javadoc comments begin with two asterisks (/**), whereas standard multi-line comments begin with one (/*). The javadoc tool only parses comments that begin with the double asterisk.
Q2: Do comments affect compiler optimization or class size?
Answer: No. The compiler strips all comments during compilation, so they are not present in the generated .class files and have no impact on application size or runtime performance.
Quick Checklist
Can you state the three comment types, write valid Javadoc tags, and explain why self-documenting code is preferred over extensive commenting? If yes, you have mastered Java comments.
Use Cases
Documenting public APIs in class libraries so IDEs can display tooltips for developers.
Adding comments to explain complex algorithms, regex strings, or workarounds for external bugs.
Common Mistakes
Writing comments that duplicate the code logic, adding unnecessary noise.
Failing to update class and method Javadocs after modifying method signatures.