AgentSkillsCN

comments

审查代码注释的质量。在审查文档或评估代码是否自文档化时使用。

SKILL.md
--- frontmatter
name: comments
description: Reviews code comments for quality. Use when reviewing documentation or evaluating if code is self-documenting.
allowed-tools: Read, Grep, Glob

Comments Reviewer

Comments should describe things not obvious from code.

Good Comments Capture

  • •Why (not what): Design rationale, why this approach over alternatives
  • •Non-obvious behavior: Side effects, constraints, invariants, performance, thread-safety
  • •Contracts: What interfaces promise, what callers need to know
  • •Cross-references: Code that must change together, non-obvious dependencies

Bad Comments

  • •Repeat the code ("increment counter by 1")
  • •State the obvious ("loop through items")
  • •Describe implementation details (become stale)

Comment Value

  • •High: Interface contracts, cross-cutting invariants
  • •Moderate: Non-obvious implementation choices (why this algorithm)
  • •Low/Harmful: Restating code, stale info, commented-out code

Output

Overall quality, balance (too few/appropriate/too many), missing documentation locations, comments to improve or remove.