skip to content

When should you write a comment in Java, and when does a comment signal a deeper code-quality problem?

level: middleimportance: should knowfreq 50%

answer

  1. Why, not what
  2. Self-documenting code beats comments
  3. Javadoc = the API contract
  4. Stale comment worse than none
  5. Comment-to-explain = refactor smell

basics

~20 s

Comment to explain WHY, not WHAT. If a comment just restates the code, rename things or extract a method instead. Use Javadoc for public APIs. Comments that explain confusing code often mean the code should be made clearer.

solid answer

~50 s

Good comments explain *why* — intent, trade-offs, non-obvious constraints, links to a ticket or spec, warnings about gotchas. They should not restate *what* the code already says; `i++; // increment i` adds nothing. Prefer making the code self-explanatory through good names and small, well-named methods, and reserve comments for context the code cannot convey. Public API elements deserve Javadoc describing contract: parameters, return value, thrown exceptions, and behavior. A comment that exists to explain a confusing line is often a smell — the better fix is usually to refactor (extract a method, rename a variable) so the comment becomes unnecessary. Also beware that comments rot: code changes but the comment is forgotten, so a stale comment is worse than none. Use TODO/FIXME sparingly and track them. In short: comments are for the *why* and for published contracts; everything else should be expressed in code.

go deeper

for a junior

Know that comments should explain why, use Javadoc for APIs, and avoid restating the obvious.

for a middle

Discuss self-documenting code, comment rot, and refactoring instead of explaining confusing code.

for a senior

Weigh comment trade-offs, treat Javadoc as a contract, and recognize legitimate exceptions (algorithms, perf hacks).

for a principal

Set team conventions/linting for docs, balance API documentation cost, and tie deprecation/doc-as-code into the maintenance and tooling strategy.

### The core principle: comment the *why*, not the *what* Well-written code already says *what* it does. A comment earns its place when it explains something the code **cannot** express: - **Why** a particular approach was chosen (or a faster one rejected). - **Non-obvious constraints** ('must stay in sync with the DB enum', 'order matters because…'). - **Warnings/gotchas** ('do not call this off the UI thread'). - **References** to a bug ticket, RFC, or spec. A comment that just narrates the code is noise: ```java int count = 0; // set count to zero <-- adds nothing ``` ### Make the code self-documenting first Before writing a comment, ask whether a rename or refactor would remove the need: ```java // bad: needs a comment if (u.a > 30 && u.s == 1) { ... } // active adult user // better: the code reads itself if (user.isAdult() && user.isActive()) { ... } ``` Extracting well-named methods and variables often *is* the documentation. ### Javadoc: comments as the API contract For anything public (a library API, a service boundary), Javadoc is the contract. Document: - `@param` — each parameter's meaning and valid range. - `@return` — what comes back, including null/empty semantics. - `@throws` — when each exception is thrown. - Overall behavior, thread-safety, side effects. Here the comment is *not* redundant — the signature alone can't state these semantics. ### Comment rot — the hidden cost Code is enforced by the compiler; comments are not. When code changes and the comment doesn't, you get a **stale comment** that actively misleads. A misleading comment is **worse than no comment**. This is a strong argument for minimizing 'what' comments (they go stale fastest) and keeping the remaining comments close to and tightly coupled with the thing they describe. ### TODO / FIXME / deprecation - `// TODO:` and `// FIXME:` are fine as breadcrumbs but should be tracked (issue link) so they don't accumulate. - For deprecation, prefer the `@Deprecated` annotation (compiler-enforced, shows in tooling) plus a Javadoc `@deprecated` tag explaining the replacement — not a plain comment. ### When a comment is a smell If you *need* a comment to understand a line, that's often a signal the line should be simpler. The comment is treating the symptom; refactoring treats the cause. Exceptions: genuinely complex algorithms, performance hacks, and external-constraint workarounds legitimately need explanation. ### Summary checklist - Explains *why*, a constraint, or a gotcha → keep. - Restates the code → delete, improve names instead. - Public API → Javadoc the contract. - Could go stale → minimize and co-locate.

  • Why is a stale comment considered worse than no comment?
    Because nothing enforces comment accuracy. A wrong comment actively misleads the reader into false assumptions, whereas its absence at least forces them to read the code.
  • What's the better way to mark a method deprecated than a // comment?
    Use the @Deprecated annotation (compiler- and IDE-aware) together with a Javadoc @deprecated tag that names the replacement, so tooling can warn callers.

saying these in an interview costs you the question

  • Believing more comments always means better code
  • Restating the code in a comment (i++ // increment i)
  • Letting comments drift out of sync with code
  • Using a plain // comment instead of @Deprecated for deprecation

context

resolving links…