review-clean-code

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Clean Code Review

Clean Code 代码评审

Focused on 7 high-impact review dimensions based on "Clean Code" principles.

聚焦于基于《Clean Code》原则的7个高影响力评审维度。

Review Workflow

评审工作流

Review Progress:
- [ ] 1. Scan codebase: identify files to review
- [ ] 2. Check each dimension (naming, functions, DRY, YAGNI, magic numbers, clarity, conventions)
- [ ] 3. Rate severity (High/Medium/Low) for each issue
- [ ] 4. Generate report sorted by severity

评审进度:
- [ ] 1. 扫描代码库: 确定需要评审的文件
- [ ] 2. 检查每个维度（命名、函数、DRY、YAGNI、魔术数字、代码清晰度、编码规范）
- [ ] 3. 为每个问题评定严重程度（高/中/低）
- [ ] 4. 生成按严重程度排序的评审报告

Core Principle: Preserve Functionality

核心原则：保留功能

All suggestions target implementation approach only—never suggest changing the code's functionality, output, or behavior.

所有建议仅针对实现方式——绝不建议修改代码的功能、输出或行为。

Check Dimensions

检查维度

1. Naming Issues【Meaningful Names】

1. 命名问题【有意义的命名】

Check for:

Meaningless names like
```
data1
```
,
```
temp
```
,
```
result
```
,
```
info
```
,
```
obj
```
Inconsistent naming for same concepts (
```
get
```
/
```
fetch
```
/
```
retrieve
```
mixed)

typescript

// ❌ 
const d = new Date();
const data1 = fetchUser();

// ✅ 
const currentDate = new Date();
const userProfile = fetchUser();

检查内容:

无意义的命名，如
```
data1
```
、
```
temp
```
、
```
result
```
、
```
info
```
、
```
obj
```
同一概念的命名不一致（混合使用
```
get
```
/
```
fetch
```
/
```
retrieve
```
）

typescript

// ❌ 
const d = new Date();
const data1 = fetchUser();

// ✅ 
const currentDate = new Date();
const userProfile = fetchUser();

2. Function Issues【Small Functions + SRP】

2. 函数问题【小函数 + 单一职责原则】

Check for:

Functions exceeding 100 lines
More than 3 parameters
Functions doing multiple things

typescript

// ❌ 7 parameters
function processOrder(user, items, address, payment, discount, coupon, notes)

// ✅ Use parameter object
interface OrderParams { user: User; items: Item[]; shipping: Address; payment: Payment }
function processOrder(params: OrderParams)

检查内容:

函数代码超过100行
参数数量超过3个
函数承担多项职责

typescript

// ❌ 7个参数
function processOrder(user, items, address, payment, discount, coupon, notes)

// ✅ 使用参数对象
interface OrderParams { user: User; items: Item[]; shipping: Address; payment: Payment }
function processOrder(params: OrderParams)

3. Duplication Issues【DRY】

3. 代码重复问题【DRY原则】

Check for:

Similar if-else structures
Similar data transformation/error handling logic
Copy-paste traces

检查内容:

相似的if-else结构
相似的数据转换/错误处理逻辑
存在复制粘贴痕迹

4. Over-Engineering【YAGNI】

4. 过度设计问题【YAGNI原则】

Check for:

```
if (config.legacyMode)
```
branches that are never true
Interfaces with only one implementation
Useless try-catch or if-else

typescript

// ❌ YAGNI violation: unused compatibility code
if (config.legacyMode) {
  // 100 lines of compatibility code
}

检查内容:

永远不会为true的
```
if (config.legacyMode)
```
分支
只有一个实现类的接口
无用的try-catch或if-else

typescript

// ❌ 违反YAGNI原则：未使用的兼容代码
if (config.legacyMode) {
  // 100行兼容代码
}

5. Magic Numbers【Avoid Hardcoding】

5. 魔术数字问题【避免硬编码】

Check for:

Bare numbers without explanation
Hardcoded strings

typescript

// ❌ 
if (retryCount > 3) // What is 3?
setTimeout(fn, 86400000) // How long is this?

// ✅ 
const MAX_RETRY_COUNT = 3;
const ONE_DAY_MS = 24 * 60 * 60 * 1000;

检查内容:

无解释的裸数字
硬编码的字符串

typescript

// ❌ 
if (retryCount > 3) // 3代表什么？
setTimeout(fn, 86400000) // 这是多长时间？

// ✅ 
const MAX_RETRY_COUNT = 3;
const ONE_DAY_MS = 24 * 60 * 60 * 1000;

6. Structural Clarity【Readability First】

6. 结构清晰度问题【可读性优先】

Check for:

Nested ternary operators
Overly compact one-liners
Deep conditional nesting (> 3 levels)

typescript

// ❌ Nested ternary
const status = a ? (b ? 'x' : 'y') : (c ? 'z' : 'w');

// ✅ Use switch or if/else
function getStatus(a, b, c) {
  if (a) return b ? 'x' : 'y';
  return c ? 'z' : 'w';
}

检查内容:

嵌套三元运算符
过于紧凑的单行代码
深层条件嵌套（超过3层）

typescript

// ❌ 嵌套三元运算符
const status = a ? (b ? 'x' : 'y') : (c ? 'z' : 'w');

// ✅ 使用switch或if/else
function getStatus(a, b, c) {
  if (a) return b ? 'x' : 'y';
  return c ? 'z' : 'w';
}

7. Project Conventions【Consistency】

7. 项目规范问题【一致性】

Check for:

Mixed import order (external libs vs internal modules)
Inconsistent function declaration styles
Mixed naming conventions (camelCase vs snake_case)

typescript

// ❌ Inconsistent style
import { api } from './api'
import axios from 'axios'  // External lib should come first
const handle_click = () => { ... }  // Mixed naming style

// ✅ Unified style
import axios from 'axios'
import { api } from './api'
function handleClick(): void { ... }

[!TIP] Project conventions should refer to
CLAUDE.md
,
AGENTS.md
, or project-defined coding standards.

检查内容:

导入顺序混乱（外部库与内部模块混合）
函数声明风格不一致
命名规范混合（camelCase与snake_case混用）

typescript

// ❌ 风格不一致
import { api } from './api'
import axios from 'axios'  // 外部库应放在前面
const handle_click = () => { ... }  // 命名风格混合

// ✅ 统一风格
import axios from 'axios'
import { api } from './api'
function handleClick(): void { ... }

[!TIP] 项目规范应参考
CLAUDE.md
、
AGENTS.md
或项目定义的编码标准。

Severity Levels

严重程度等级

Level	Criteria
High	Affects maintainability/readability, should fix immediately
Medium	Room for improvement, recommended fix
Low	Code smell, optional optimization

等级	判定标准
高	影响可维护性/可读性，需立即修复
中	有改进空间，建议修复
低	代码坏味道，可选优化

Output Format

输出格式

markdown

undefined

markdown

undefined

[Issue Type]: [Brief Description]

[问题类型]: [简要描述]

Principle: [Clean Code principle]
Location:
```
file:line
```
Severity: High/Medium/Low
Issue: [Specific description]
Suggestion: [Fix direction]

undefined

原则: [Clean Code原则]
位置:
```
file:line
```
严重程度: 高/中/低
问题: [具体描述]
建议: [修复方向]

undefined

Artifacts (Pipeline Mode)

产物（流水线模式）

Output:
```
clean-code-review.md
```
(human-readable report)
Output:
```
clean-code-review.json
```
(structured issue list for aggregation/deduplication/statistics)

输出:
```
clean-code-review.md
```
（人类可读报告）
输出:
```
clean-code-review.json
```
（结构化问题列表，用于聚合/去重/统计）

References

参考资料

Detailed examples: See detailed-examples.md

Complete cases for each dimension (naming, functions, DRY, YAGNI, magic numbers)

Language patterns: See language-patterns.md

TypeScript/JavaScript common issues
Python common issues
Go common issues

详细示例: 查看detailed-examples.md

每个维度的完整案例（命名、函数、DRY、YAGNI、魔术数字）

语言模式: 查看language-patterns.md

TypeScript/JavaScript常见问题
Python常见问题
Go常见问题

Multi-Agent Parallel

多Agent并行处理

Split by the following dimensions for parallel multi-agent execution:

By check dimension - One agent per dimension (7 total)
By module/directory - One agent per module
By language - One agent each for TypeScript, Python, Go
By file type - Components, hooks, utilities, type definitions

Example:

/review-clean-code --scope=components

--dimension=naming

Deduplication and unified severity rating needed when aggregating.

可按以下维度拆分进行多Agent并行执行:

按检查维度 - 每个维度分配一个Agent（共7个）
按模块/目录 - 每个模块分配一个Agent
按语言 - TypeScript、Python、Go各分配一个Agent
按文件类型 - 组件、钩子、工具函数、类型定义

示例:

/review-clean-code --scope=components

或

--dimension=naming

聚合结果时需要进行去重与统一严重程度评级。