clean-code-reviewer

# Clean Code Review

基于《代码整洁之道》原则，聚焦 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 (高/中/低) for each issue
- [ ] 4. Generate report sorted by severity
```

## 核心原则：功能保留

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

## Check Dimensions

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

检查标志：
- `data1`, `temp`, `result`, `info`, `obj` 等无意义命名
- 同一概念多种命名（`get`/`fetch`/`retrieve` 混用）

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

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

### 2. 函数问题【函数短小 + SRP】

检查标志：
- 函数超过 **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. 重复问题【DRY】

检查标志：
- 相似的 if-else 结构
- 相似的数据转换/错误处理逻辑
- Copy-paste 痕迹

### 4. 过度设计【YAGNI】

检查标志：
- 从未为 true 的 `if (config.legacyMode)` 分支
- 只有一个实现的接口
- 无用的 try-catch 或 if-else

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

### 5. 魔法数字【避免硬编码】

检查标志：
- 裸露数字无解释
- 硬编码字符串

```typescript
// ❌ 
if (retryCount > 3) // 3 是什么？
setTimeout(fn, 86400000) // 这是多久？

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

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

检查标志：
- 嵌套三元运算符
- 过度紧凑的单行代码
- 过深的条件嵌套（> 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. 项目规范【一致性】

检查标志：
- import 顺序混乱（外部库 vs 内部模块）
- 函数声明风格不一致
- 命名规范不统一（camelCase vs 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

| 级别 | 标准 |
|------|------|
| 高 | 影响可维护性/可读性，应立即修复 |
| 中 | 有改进空间，建议修复 |
| 低 | 代码气味，可选优化 |

## Output Format

```markdown
### [问题类型]: [简述]

- **原则**: [Clean Code 原则]
- **位置**: `文件:行号`
- **级别**: 高/中/低
- **问题**: [具体描述]
- **建议**: [修复方向]
```

## References

**Detailed examples**: See [references/detailed-examples.md](references/detailed-examples.md)
- 各维度的完整案例（命名、函数、DRY、YAGNI、魔法数字）

**Language patterns**: See [references/language-patterns.md](references/language-patterns.md)
- TypeScript/JavaScript 常见问题
- Python 常见问题
- Go 常见问题

## Multi-Agent Parallel

按以下维度拆分给多 agent 并行：

1. **按检查维度** - 7 维度各一个 agent
2. **按模块/目录** - 不同模块各一个 agent
3. **按语言** - TypeScript、Python、Go 各一个 agent
4. **按文件类型** - 组件、hooks、工具函数、类型定义

示例：`/clean-code-reviewer --scope=components` 或 `--dimension=naming`

汇总时需去重和统一严重程度评定。