Back to Details

review-comments

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Review Comments

注释检查

Review code comments for quality, then offer to fix issues found.
检查代码注释的质量，然后针对发现的问题提供修复方案。

Flags

可用参数

  • --staged
    - git staged files
  • --changed
    - git unstaged changes
  • --all
    - entire codebase (parallel agents)
  • --fix
    - auto-apply fixes (remove + refactor) without prompting
  • Default: 
    --staged --changed
    combined
  • --staged
    - git暂存区文件
  • --changed
    - git未暂存变更
  • --all
    - 整个代码库（并行Agent处理）
  • --fix
    - 无需提示自动应用修复（删除+重构）
  • 默认：组合使用
    --staged --changed

Usage

使用方法

/review-comments              # staged + changed (default)
/review-comments --all        # entire codebase
/review-comments --fix        # review and auto-fix
/review-comments              # 暂存区+未暂存变更（默认）
/review-comments --all        # 整个代码库
/review-comments --fix        # 检查并自动修复

Workflow

工作流程

Step 1: Parse Flags

步骤1：解析参数

From 
$ARGUMENTS
, determine scope:
Flags PresentScope
(none)
--staged --changed
--all
Entire codebase
--staged
Staged files only
--changed
Unstaged files only
--staged --changed
Both
从
$ARGUMENTS
中确定检查范围：
携带参数检查范围
无
--staged --changed
--all
整个代码库
--staged
仅暂存区文件
--changed
仅未暂存变更文件
--staged --changed
两者都包含

Step 2: Get File List

步骤2：获取文件列表

For --staged:
bash
git diff --cached --name-only
For --changed:
bash
git diff --name-only
For --all:
bash
undefined
针对--staged参数：
bash
git diff --cached --name-only
针对--changed参数：
bash
git diff --name-only
针对--all参数：
bash
undefined

Use Glob to find all source files

Use Glob to find all source files

**/*.{ts,tsx,js,jsx,py,go,java,kt,swift,rs,c,cpp,h,hpp,cs,rb,php}

Filter to only source code files (exclude node_modules, build dirs, etc.).
**/*.{ts,tsx,js,jsx,py,go,java,kt,swift,rs,c,cpp,h,hpp,cs,rb,php}

仅保留源代码文件（排除node_modules、构建目录等）。

Step 3: Review Comments

步骤3：检查注释

For --staged/--changed (small file lists): Review files directly - read each file and analyze comments.
For --all (large codebase): Split files into batches and spawn parallel sub-agents:
  1. Get all source files
  2. Split into batches of ~20 files each
  3. Spawn sub-agents in parallel using Task tool:
Subagent type: general-purpose
Prompt per batch:
---
Review comments in these files for quality issues:
{file_list}

For each file, identify:
1. "What" comments that should be "why" comments
2. Comments that could be replaced with better function/variable names
3. Obvious/redundant comments

Return findings in this format:
针对--staged/--changed（少量文件）： 直接检查文件 - 读取每个文件并分析注释。
针对--all（大型代码库）： 将文件拆分成批次，启动并行子Agent：
  1. 获取所有源代码文件
  2. 拆分为每批次约20个文件
  3. 使用Task工具并行启动子Agent：
Subagent type: general-purpose
Prompt per batch:
---
Review comments in these files for quality issues:
{file_list}

For each file, identify:
1. "What" comments that should be "why" comments
2. Comments that could be replaced with better function/variable names
3. Obvious/redundant comments

Return findings in this format:

{filename}

{filename}

  • Line {n}: "{comment}" → {suggestion}

4. Collect and merge results from all agents
  • Line {n}: "{comment}" → {suggestion}

4. 收集并合并所有Agent的返回结果

Step 4: Report Findings

步骤4：上报检查结果

markdown
undefined
markdown
undefined

Comment Review: {scope}

注释检查：{scope}

Issues Found

发现的问题

{filename}

{filename}

LineCurrent CommentIssueSuggestion
{n}"{comment}"What not Why{suggestion}
行号当前注释问题类型修改建议
{n}"{comment}"仅说明是什么而非为什么{suggestion}

Summary

汇总

  • Files reviewed: {count}
  • Issues found: {count}
  • Most common issue: {type}
undefined
  • 已检查文件数：{count}
  • 发现问题数：{count}
  • 最常见问题：{type}
undefined

Step 5: Offer to Fix

步骤5：提供修复选项

If 
--fix
flag is present: Skip the prompt and directly apply Option 2 (Remove and refactor).
Otherwise, if issues were found, ask the user:
Found {n} low-quality comments. How would you like to proceed?

1. **Remove all** - Delete all flagged comments
2. **Remove and refactor** - Delete comments + extract better function/variable names where suggested
3. **Cherry-pick** - Show me each one and I'll decide
4. **Skip** - Keep the report, don't change anything
Based on user choice:
Option 1 (Remove all):
  • Use Edit tool to remove each flagged comment
  • Report: "Removed {n} comments from {m} files"
Option 2 (Remove and refactor):
  • Remove comments
  • Where suggestion was "extract to function" or "rename variable", apply that refactor
  • Report changes made
Option 3 (Cherry-pick):
  • Present each issue one at a time: "Line 42: 
    // increment counter
    - Remove? (y/n/stop)"
  • Apply user's choices
Option 4 (Skip):
  • End without changes
如果携带了
--fix
参数： 跳过提示，直接执行选项2（删除并重构）。
否则，如果发现了问题，询问用户：
发现{n}条低质量注释，你想要如何处理？

1. **全部删除** - 删除所有标记的问题注释
2. **删除并重构** - 删除注释，同时按照建议优化函数/变量名
3. **逐个选择** - 逐条展示问题，由我决定如何处理
4. **跳过** - 保留检查报告，不做任何修改
根据用户选择执行对应操作：
选项1（全部删除）：
  • 使用编辑工具删除所有标记的问题注释
  • 上报结果：「已从{m}个文件中删除{n}条注释」
选项2（删除并重构）：
  • 删除问题注释
  • 针对建议为「提取为函数」或「重命名变量」的场景，执行对应的重构操作
  • 上报已完成的修改
选项3（逐个选择）：
  • 逐个展示每个问题：「Line 42: 
    // increment counter
    - 是否删除？(y/n/stop)」
  • 按照用户选择执行操作
选项4（跳过）：
  • 结束流程，不做任何修改

Comment Quality Guidelines

注释质量指南

Good Comments (WHY)

优质注释（说明为什么）

  • Explain business logic decisions
  • Document performance considerations
  • Clarify non-obvious algorithms
  • Explain workarounds or edge cases
  • Document assumptions or constraints
  • 解释业务逻辑决策
  • 说明性能相关考量
  • 阐明不易理解的算法
  • 解释临时方案或边界场景处理逻辑
  • 说明假设条件或约束

Bad Comments (WHAT)

低质量注释（说明是什么）

  • Describe what the code is doing syntactically
  • Restate variable names or method calls
  • Explain obvious operations
  • Add noise without value
  • 仅描述代码语法层面的操作
  • 重复变量名或方法调用的含义
  • 解释显而易见的操作
  • 无价值的冗余内容

Better Alternatives

更优替代方案

Instead of "what" comments, prefer:
  • Extracting functions with descriptive names
  • Using meaningful variable names
  • Writing self-documenting code
与其写「是什么」类的注释，更推荐：
  • 提取命名清晰的函数
  • 使用有意义的变量名
  • 编写自解释代码

Examples

示例

Bad Comment

低质量注释

python
undefined
python
undefined

Loop through users and check if active

Loop through users and check if active

for user in users: if user.is_active: active_users.append(user)
undefined
for user in users: if user.is_active: active_users.append(user)
undefined

Good Refactor

优质重构

python
active_users = [u for u in users if u.is_active]
python
active_users = [u for u in users if u.is_active]

Or extract to: active_users = filter_active_users(users)

Or extract to: active_users = filter_active_users(users)

undefined
undefined

Good Comment (when needed)

必要的优质注释

python
undefined
python
undefined

Use binary search here because users list is sorted and can exceed 100k items

Use binary search here because users list is sorted and can exceed 100k items

index = bisect.bisect_left(sorted_users, target_user)
undefined
index = bisect.bisect_left(sorted_users, target_user)
undefined

Troubleshooting

故障排除

False positives on license headers or necessary comments

许可证头或必要注释被误判

Solution: License headers and legal notices are required -- skip them during review. If the tool flags doc comments (JSDoc, docstrings) or regulatory annotations, those are intentional and should be excluded from cleanup.
解决方案： 许可证头和法律声明是必要内容 -- 检查时跳过此类内容。如果工具标记了文档注释（JSDoc、docstrings）或合规相关注解，这些是有意保留的内容，应该排除在清理范围外。

Comments in unfamiliar language or framework

遇到不熟悉的语言或框架中的注释

Solution: Focus on structural patterns (e.g., comments restating the next line of code are low-quality in any language). For framework-specific annotations or directives you do not recognize, leave them in place and flag them for manual review rather than removing them.
解决方案： 聚焦于结构模式（比如重复下一行代码含义的注释在任何语言中都是低质量的）。对于你不认识的框架专属注解或指令，保留原内容，标记为需要人工检查，不要直接删除。

Notes

注意事项

  • For 
    --all
    on large codebases, parallel agents significantly speed up review
  • Focus on actionable suggestions, not nitpicks
  • If no files match the scope, report "No files to review"
  • 针对大型代码库使用
    --all
    参数时，并行Agent可以大幅提升检查速度
  • 聚焦可落地的修改建议，不要过于吹毛求疵
  • 如果没有符合范围的文件，返回「无需要检查的文件」