Best Practices for Writing Java Comments

During a recent code review, many developers were unclear about when and how to write effective Java comments. This article, compiled from internet sources and "Code Complete", shares a comprehensive guide to improve comment writing skills and produce more readable code.

1. Types of Java comments

// single‑line comment /* ... */ multi‑line comment /** ... */ Javadoc comment (used by tools like javadoc to generate API documentation).

2. Comment layout

Good comment layout greatly enhances readability. Follow two rules: (1) Indent comments to match the surrounding code; (2) Separate each comment line with at least one blank line. Misaligned comments break the visual structure of the code.

3. Functions of comments

Redundant comments – merely repeat the code without adding information.

Explanatory comments – clarify complex or obscure code blocks.

Tag comments – e.g., // TODO to mark unfinished work.

Overview comments – summarize several lines of code in a sentence.

Intent comments – state the purpose of the code rather than the implementation.

Non‑expressible information – copyright, version, author, external references, etc.

4. Efficient commenting

Effective commenting is a balance; too many comments are as harmful as too few. IBM research suggests roughly one comment per ten statements yields optimal clarity.

5. Comment techniques

Adopt a comment style that does not hinder modifications.

Use pseudo‑code before writing actual code to reduce later commenting effort.

Integrate commenting into the development workflow instead of postponing it to the end of a project.

6. Single‑line comments

Avoid end‑of‑line comments on single statements; they often duplicate the code. End‑of‑line comments are suitable for data declarations or marking the end of a block when space permits.

// Obtain current employee information

// Update employee information

7. Commenting code blocks

Place comments before control structures (if, switch, loops) to explain the reason and expected outcome. Add comments after complex blocks to summarize results.

8. Subroutine and class comments

Keep comments close to the code they describe. Use a brief one‑ or two‑sentence overview for each method, and document parameters and return values (e.g., with Javadoc). For classes, describe design intent, overall architecture, and any alternatives considered, but avoid exposing implementation details in the public interface.

9. Data declaration comments

Specify units for numeric values.

Document allowed ranges.

Explain encoding meanings (use enums when possible).

State input constraints and data sources.

Tie comments to variable names for easy search.

Annotate global variables with purpose and usage notes.

10. Control‑structure comments

Comment before each if, case, loop, or code segment.

Comment after the block to indicate the result.

Use end‑of‑block comments as a warning that the block may be too complex.

11. Subroutine comments

Place comments near the code they describe.

Provide a concise overview (except for trivial getters/setters).

Document parameters inline with their declarations.

Leverage tools like Javadoc to generate API documentation.

Describe any global side effects.

12. Class comments

Explain design rationale, overall approach, and discarded alternatives.

Document the class interface (what users need to know) without exposing internal implementation.

By following these guidelines, developers can write clear, purposeful comments that complement well‑structured code and improve overall software maintainability.