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 Present	Scope
(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

**/*.{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:

Get all source files
Split into batches of ~20 files each
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：

获取所有源代码文件
拆分为每批次约20个文件
使用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}

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}

Line	Current Comment	Issue	Suggestion
{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

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)

undefined

undefined

Good Comment (when needed)

必要的优质注释

python

undefined

python

undefined

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可以大幅提升检查速度
聚焦可落地的修改建议，不要过于吹毛求疵
如果没有符合范围的文件，返回「无需要检查的文件」