菜单
Use when writing, fixing, or editing comments or documentation in any language, especially commented-out code, stale docs, metadata comments, TODO banners, redundant comments, or unclear comment value.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | clean-general-comments |
| description | Use when writing, fixing, or editing comments or documentation in any language, especially commented-out code, stale docs, metadata comments, TODO banners, redundant comments, or unclear comment value. |
Comments shouldn't hold metadata. Use Git for author names, change history, ticket numbers, and dates. Comments are for technical notes about code only.
If a comment describes code that no longer exists or works differently, delete it immediately. Stale comments become "floating islands of irrelevance and misdirection."
# Bad - the code already says this
i += 1 # increment i
user.save() # save the user
# Good - explains WHY, not WHAT
i += 1 # compensate for zero-indexing in display
If a comment is worth writing, write it well:
# DELETE THIS
# def old_calculate_tax(income: float) -> float:
# return income * 0.15
Who knows how old it is? Who knows if it's meaningful? Delete it. Git remembers everything.
The best comment is the code itself. If you need a comment to explain what code does, refactor first, comment last.
Good comments and docstrings usually explain constraints, surprising trade-offs, external contracts, or why an obvious-looking alternative is wrong.
Use when checking code for functional correctness, backwards compatibility, logic errors, security vulnerabilities, performance issues, or missing test coverage — not style.
Use when reviewing code, pull requests, branches, diffs, or changed files for quality, correctness, security, performance, and style issues.
Use when writing, fixing, editing, or refactoring TypeScript, Python, React, or CSS code. Not for PR or diff reviews — use clean-code-reviewer for those.
Use when naming or renaming identifiers in any language, especially cryptic names, ambiguous parameters, type or scope encodings, misleading side effects, or requests for clearer names.
Use when writing, fixing, or editing code in any language with duplicated logic, magic values, unclear one-liners, mixed responsibilities, clutter, arbitrary code, or inconsistent abstraction levels.
Use when writing, fixing, or editing Python async flows, coroutines, asyncio tasks, retries, timeouts, cancellation, shared mutable state across awaits, race conditions, or flaky async tests.