comment-slop
Find and remove AI-slop comments — ones that restate the code, describe another layer's behavior, or narrate planning that never shipped — while protecting the comments that carry real reasoning. Use when a reviewer calls a comment useless, unclear, or AI-written — including one a previous cleanup pass already rewrote; when auditing or cleaning up comments and docstrings on a branch, diff, or PR; when comments should be reduced, simplified, or restyled to ASD-STE100 / simplified technical English; when writing or reviewing docstrings for completeness — tuple-return meanings, boolean polarity, silent defaults and fallbacks; when deciding whether new code needs a comment and what it should say; or before sending a change for review.
dashed · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add dashed/claude-marketplace --skill comment-slop技能说明
name: comment-slop description: "Find and remove AI-slop comments — ones that restate the code, describe another layer's behavior, or narrate planning that never shipped — while protecting the comments that carry real reasoning. Use when a reviewer calls a comment useless, unclear, or AI-written — including one a previous cleanup pass already rewrote; when auditing or cleaning up comments and docstrings on a branch, diff, or PR; when comments should be reduced, simplified, or restyled to ASD-STE100 / simplified technical English; when writing or reviewing docstrings for completeness — tuple-return meanings, boolean polarity, silent defaults and fallbacks; when deciding whether new code needs a comment and what it should say; or before sending a change for review." license: MIT
Comment Slop
A comment earns its place only if it states a fact that is:
- True at this layer — about the code it sits on, not a caller's or a callee's behavior.
- Not already visible in the code in front of the reader.
- Not stated better nearby — in the signature, in the module docstring, in a test name, or on the very next line.
Every slop comment fails one of those three clauses. That is the whole diagnosis. The rest of this skill is how to apply it, and — just as important — how to recognize the comments that pass, so a cleanup pass does not delete the reasoning that was worth keeping.
This is the operational form of the familiar rule: comment the why, not the what or the how. Code with descriptive names already tells the reader what it does, and the body is the how — a comment restating either fails clause 2. What the code cannot say is the why: context from outside the file, the business rule being implemented, the design decision that looks wrong until explained (the keep table below). But the folk rule is a compass, not a verdict — a why-shaped sentence still fails when it describes another layer or restates a convention with a documented home (see Abstracting is not the fix either). The three clauses decide, and the burden of proof sits on the comment: the default verdict is delete, and a comment that cannot show a pass does not get one.
Slop is not a length problem. It is a content-selection problem, which is why shortening or generalizing comments makes it worse rather than better (see Trimming is not the fix and Abstracting is not the fix either).
When to Use
- A reviewer says a comment is useless, confusing, or "seems like an AI comment"
- Cleaning up comments and docstrings on a branch or PR before sending it for review
- A comment uses a term the reader has to go look up, or describes machinery that is not in the file
- Auditing agent-written or generated code for filler prose
Failure modes
Each mode below is one clause of the test failing. The examples are real; the reviewer reactions are quotes from an actual review.
1. Wrong layer
The comment describes another module's semantics, written from the author's whole-call-graph vantage rather than the reader's.
def retention_config_to_proto(user_parameters: list[UserParameter]) -> RetentionConfig:
"""Project a contract's retention user parameter into the RetentionConfig proto.
No retention parameter means the contract has no override and uses the
package defaults entirely.
"""
"the comment mentions a package and I don't see a package here"
User parameters go in, a proto comes out. No package crosses this boundary. "Uses the package defaults" is the resolver's behavior, one layer up — true of the system, not of this function.
Fix: say what an empty result means at this layer ("the contract stores no override") and stop. Whoever consumes the empty proto decides what to do about it.
Fix, when the wrong-layer sentence justified a gate: replace the collaborator's behavior with the precondition itself. "An organization-level override sets the days for every category" (the setting happens two functions away) becomes "The contract must have no organization-level override." The reason moves out; the condition the body checks stays.
The boundary: describing how the function's own return is derived stays in scope even when a private helper does the arithmetic — that is still this function's input-to-output contract. Out of scope is what happens elsewhere in the system.
Heuristic: name every noun in the comment. If a noun never appears in the parameters, the return type, the body, or the things the body calls, the comment is describing somewhere else.
Second heuristic — the sibling paste-test: would the comment be just as true pasted onto the neighboring declarations in the same file? A comment equally true on every sibling documents the architecture, not this code. If the fact is worth writing down, its home is the module docstring or the convention doc — not one method among the many it applies to.
2. Redundant with the line next to it
# The endpoint proto replaces the dataclass request. It also adds `@service_method`.
# TODO: add @service_method and switch to the endpoint proto.
"Seems like a useless AI comment?"
The TODO already carries the fact, in the imperative, in the form someone can act on. The sentence above it is the same fact restated as description.
Fix: delete the prose, keep the TODO. When two adjacent comments say one thing, keep the one that is actionable.
3. Undefined term at the point of use
# The caller resolves the current (unsealed) contract
"What does 'unsealed' mean?"
"Sealed" was defined in the module docstring 200 lines above, and this comment uses the negation of that term, so the reader has to find the definition and then invert it.
The instinct is to define the term inline. Check first whether the term is needed at all. Here it was not: the "current contract" query already selects on the absence of a usage invoice, which is the definition of unse
阅读完整来源 ↗