Java Clean Comments

---
name: java-clean-comments
description: Enforces comment and Javadoc hygiene in Java — no commented-out code, no author or ticket metadata, no comments restating the code, and Javadoc that documents contracts rather than repeating signatures. Use when writing or reviewing Java comments and Javadoc, and when the code shows commented-out blocks, TODO or FIXME banners, @author or date tags, boilerplate Javadoc, or documentation that no longer matches the method.
---

# Clean comments in Java

A comment is a failure to express the idea in code. Sometimes it is the right failure — but try the code first.

## Prefer code that needs no comment

```java
// Bad
// Check if the employee is eligible for full benefits
if (employee.flags() == HOURLY_FLAG && employee.age() > 65) { ... }

// Good
if (employee.isEligibleForFullBenefits()) { ... }
```

```java
// Bad
int t = 86_400; // seconds in a day

// Good
static final int SECONDS_PER_DAY = 86_400;
```

## Delete commented-out code

```java
// Bad
public void process(Order order) {
    validate(order);
    // legacy path, keep for now
    // if (order.isLegacy()) {
    //     legacyProcessor.handle(order);
    //     return;
    // }
    save(order);
}
```

Nobody dares delete it later because nobody knows if it matters. Git has it. Delete it.

## No metadata

```java
// Bad
/**
 * @author j.smith
 * @since 2019-04-03
 * Modified by: a.jones (JIRA-4821)
 */
```

Version control owns authorship, dates, and ticket history, and keeps them accurate — comments drift immediately. `@since` on a public API version (`@since 2.4`) is legitimate; a calendar date is not.

## No redundant Javadoc

```java
// Bad — every line restates the signature
/**
 * Gets the name.
 * @param id the id
 * @return the name
 */
public String getName(String id)
```

Javadoc that only echoes the signature adds lines and hides the ones that matter. Write it when there is a contract to state:

```java
/**
 * Transfers funds between accounts atomically.
 *
 * @param amount must be positive
 * @throws InsufficientFundsException if {@code from} cannot cover {@code amount}
 * @throws IllegalArgumentException if {@code amount} is zero or negative
 */
public void transfer(Account from, Account to, Money amount)
```

Document the things a signature cannot say: preconditions, thrown exceptions and when, thread safety, nullability, mutability of returned collections, units and ranges. Public API gets Javadoc; a private method with a clear name usually does not.

## TODO and FIXME

A TODO with no owner and no date is permanent. Either fix it now, or file an issue and reference it:

```java
// TODO(PLAT-1182): remove once the v1 endpoint is retired
```

`FIXME` in committed code means "known broken and shipped anyway" — resolve it before merge.

## Comments that earn their place

Explain **why**, never what:

```java
// The vendor API rejects more than 50 ids per call, undocumented.
var batches = Lists.partition(ids, 50);
```

```java
// Retry only on 429: the gateway returns 500 for permanent validation
// failures, and retrying those doubles the charge.
```

Also legitimate: warning of consequences, clarifying a non-obvious regex or algorithm, explaining a deliberate deviation from the obvious approach, and `@Deprecated` with a `@deprecated` tag naming the replacement.

## Keep them true

A comment that contradicts the code is worse than none — readers trust it and are misled. When you change a method, read its comment. If it no longer holds, fix or delete it in the same commit.

## Do not comment out a closing brace

```java
} // end for
```

If a block is long enough to need this, shorten the block.