Agent Skills › simstudioai/sim › you-might-not-need-a-comment

you-might-not-need-a-comment

GitHub

分析并修复冗余或自解释的内联注释,去除噪音,将真实文档转换为 TSDoc。遵循代码即文档原则,仅保留解释非显而易见原因的注释。

.agents/skills/you-might-not-need-a-comment/SKILL.md simstudioai/sim

触发场景

代码审查中发现冗余注释 需要清理内联注释以符合规范

安装

npx skills add simstudioai/sim --skill you-might-not-need-a-comment -g -y
更多选项

非标准路径

npx skills add https://github.com/simstudioai/sim/tree/main/.agents/skills/you-might-not-need-a-comment -g -y

不安装直接使用

npx skills use simstudioai/sim@you-might-not-need-a-comment

指定 Agent (Claude Code)

npx skills add simstudioai/sim --skill you-might-not-need-a-comment -a claude-code -g -y

安装 repo 全部 skill

npx skills add simstudioai/sim --all -g -y

预览 repo 内 skill

npx skills add simstudioai/sim --list

SKILL.md

Frontmatter
{
    "name": "you-might-not-need-a-comment",
    "description": "Analyze and fix redundant or self-explanatory inline comments — remove noise, promote genuine documentation to TSDoc",
    "argument-hint": "[scope] [fix=true|false]"
}

You Might Not Need a Comment

Arguments:

  • scope: what to analyze (default: your current changes). Examples: "diff to staging", "PR #123", "src/components/", "whole codebase"
  • fix: whether to apply fixes (default: true). Set to false to only propose changes.

User arguments: $ARGUMENTS

The one rule that matters

A comment must add information the code cannot express itself. Code says what and how; a comment earns its place only by explaining why — a non-obvious constraint, a workaround, a decision, a gotcha. If deleting the comment loses no information a competent reader wouldn't recover from the code in seconds, delete it.

This codebase's convention: TSDoc for documentation; an inline // only for a terse non-obvious why or a script-enforced annotation; no ==== separators. Genuine documentation belongs in a /** ... */ block on the declaration; everything that survives as an inline // comment must be a real why, kept terse.

Anti-patterns to detect

  1. Restates the code: // increment counter above counter++, // return the result above return result, // loop over items. Delete.
  2. Narrates the obvious from names: the function is fetchUserById, the comment says // fetches a user by id. The identifier already said it. Delete.
  3. Section-divider / banner comments: // ==== Helpers ====, // --- state ---, // #region. Against convention. Delete (the code's structure is the structure).
  4. Commented-out code: dead code left as a comment. Delete — git is the history.
  5. Redundant type/param echo in prose comments: // takes a string and returns a number when the signature already says so. Delete.
  6. Changelog / attribution noise: // added by X, // TODO(2021): ... long-stale, // fix for bug. Delete unless it encodes a live, actionable constraint.
  7. Genuine documentation written as a loose // block on a declaration: a real explanation of what an exported function/type/const is for, but written as stacked // lines instead of TSDoc. Convert to a /** ... */ TSDoc block on the declaration.

Patterns that ARE correct — do not flag

  • A // comment that explains a non-obvious why: a workaround for an upstream bug, an ordering constraint, a perf reason, a spec/edge-case the code can't self-document (// first-match wins — matches the old find() semantics).
  • Existing TSDoc /** ... */ blocks on declarations — leave them (only tighten if verbose).
  • // boundary-raw-fetch:, // double-cast-allowed:, // boundary-raw-json:, // untyped-response:, -- migration-safe: (SQL migrations), // rq-lint-allow:, // client-boundary-allow: and any other <kebab-tag>: <reason> annotation a script under scripts/ greps for, in line-comment or block-comment form (e.g. the /** svg-path-precision-exception: ... */ directive on icon paths) — these are load-bearing, never touch them.
  • // biome-ignore, // @ts-expect-error and other tooling directives. (Nothing runs ESLint, so eslint-disable/eslint-enable directives are dead; delete them — check:comment-hygiene rejects both.)
  • // TODO / // FIXME that point at real, still-open work.

Bias

Prefer deletion over rewriting, and no comment over a comment when the code is already clear. When a comment is genuine documentation, prefer promoting it to terse TSDoc over leaving a loose // block. Never add new comments in this pass — this is a reduction pass. When unsure whether a comment encodes a real why, keep it.

Steps

  1. Analyze the specified scope for the anti-patterns listed above
  2. If fix=true, apply the fixes. If fix=false, propose the fixes without applying.

版本历史

  • c6cef5f 当前 2026-10-20 02:39

    更新 scope 默认值为当前变更;移除被废弃的 ESLint 指令相关检测逻辑。

  • 8725250 2026-09-28 17:01

    更新注释规范:明确允许脚本强制使用的特定 kebab-tag 注解(如 boundary-raw-fetch)及工具指令(如 biome-ignore),不再一律删除非 TSDoc 注释;细化了需保留的例外情况。

  • 6dfb467 2026-09-23 06:37

    移除过时的模式和冗余内容,修正审查相关的提供程序矩阵及仓库特定声明。

  • ceda457 2026-08-20 15:29

同 Skill 集合

.agents/skills/add-block-preview/SKILL.md
.agents/skills/add-block/SKILL.md
.agents/skills/add-column-type/SKILL.md
.agents/skills/add-connector/SKILL.md
.agents/skills/add-enrichment/SKILL.md
.agents/skills/add-feature-flag/SKILL.md
.agents/skills/add-hosted-key/SKILL.md
.agents/skills/add-integration/SKILL.md
.agents/skills/add-managed-cli/SKILL.md
.agents/skills/add-model/SKILL.md
.agents/skills/add-permission-group-item/SKILL.md
.agents/skills/add-selector/SKILL.md
.agents/skills/add-settings-page/SKILL.md
.agents/skills/add-tools/SKILL.md
.agents/skills/add-trigger/SKILL.md
.agents/skills/babysit/SKILL.md
.agents/skills/cleanup/SKILL.md
.agents/skills/council/SKILL.md
.agents/skills/db-migrate/SKILL.md
.agents/skills/design-taste-frontend/SKILL.md
.agents/skills/emcn-design-review/SKILL.md
.agents/skills/emil-design-eng/SKILL.md
.agents/skills/make-interfaces-feel-better/SKILL.md
.agents/skills/memory-load-check/SKILL.md
.agents/skills/react-query-best-practices/SKILL.md
.agents/skills/ship/SKILL.md
.agents/skills/test-audit/SKILL.md
.agents/skills/tool-registry-boundary/SKILL.md
.agents/skills/v2-api-conventions/SKILL.md
.agents/skills/validate-connector/SKILL.md
.agents/skills/validate-integration/SKILL.md
.agents/skills/validate-model/SKILL.md
.agents/skills/validate-permission-group-item/SKILL.md
.agents/skills/validate-selector/SKILL.md
.agents/skills/validate-trigger/SKILL.md
.agents/skills/you-might-not-need-a-callback/SKILL.md
.agents/skills/you-might-not-need-a-memo/SKILL.md
.agents/skills/you-might-not-need-an-effect/SKILL.md
.agents/skills/you-might-not-need-state/SKILL.md
.agents/skills/you-might-not-need-url-state/SKILL.md
.claude/skills/add-settings-page/SKILL.md
helm/sim/.claude/skills/sim-helm/SKILL.md
.agents/skills/migrate-application-operation/SKILL.md

元信息

文件数
0
版本
c6cef5f
Hash
fa710487
收录时间
2026-08-20 15:29

首页 - Wiki
Copyright © 2011-2026 iteam. Current version is 2.156.0. UTC+08:00, 2026-11-21 16:28
浙ICP备14020137号-1