How do I install the Java Clean Comments skill?

Run npx skillmds@latest add caslubbers/java-clean-comments in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Java Clean Comments safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Java Clean Comments?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Java Clean Comments free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Java Clean Comments?

CasLubbers (@caslubbers) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Java Clean Comments by caslubbers — Agent Skill

Name: Java Clean Comments
Author: CasLubbers

Java Clean Comments

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.

CasLubbers 9e9a7b3 3.6 KB Updated Sep 17, 2026

File contents

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

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

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

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

// Good
static final int SECONDS_PER_DAY = 86_400;

Delete commented-out code

// 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

// 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

// 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:

/**
 * 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:

// 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:

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

// 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

} // end for

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

---name: java-clean-commentsdescription: 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 JavaA 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 benefitsif (employee.flags() == HOURLY_FLAG && employee.age() > 65) { ... }// Goodif (employee.isEligibleForFullBenefits()) { ... }``````java// Badint t = 86_400; // seconds in a day// Goodstatic final int SECONDS_PER_DAY = 86_400;```## Delete commented-out code```java// Badpublic 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 FIXMEA 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 placeExplain **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 trueA 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.

Frequently asked questions