# 代码审查指南

本文档介绍 ByClaw 项目的代码审查流程和标准。

## 审查原则

1. **友善** - 保持建设性和尊重
2. **及时** - 尽快回应审查请求
3. **全面** - 检查功能、性能、安全
4. **学习** - 相互学习，共同成长

## 审查清单

### 功能性

- [ ] 代码是否正确实现了功能
- [ ] 是否处理了边界情况
- [ ] 是否有适当的错误处理
- [ ] 日志记录是否恰当

### 代码质量

- [ ] 代码是否清晰易读
- [ ] 命名是否有意义
- [ ] 是否避免了重复代码
- [ ] 函数/类是否职责单一

### 测试

- [ ] 是否有足够的单元测试
- [ ] 测试是否覆盖了主要场景
- [ ] 测试是否易于理解
- [ ] 所有测试是否通过

### 文档

- [ ] 代码注释是否清晰
- [ ] API 文档是否更新
- [ ] 用户文档是否需要更新
- [ ] CHANGELOG 是否更新

### 性能

- [ ] 是否有性能问题
- [ ] 是否有不必要的计算
- [ ] 数据库查询是否优化
- [ ] 是否有内存泄漏风险

### 安全性

- [ ] 是否有 SQL 注入风险
- [ ] 是否有 XSS 风险
- [ ] 敏感数据是否加密
- [ ] 权限检查是否完善

## 审查流程

### 对于审查者

1. **查看 PR 描述** - 理解变更目的
2. **阅读代码** - 理解实现逻辑
3. **检查清单** - 逐项检查
4. **添加评论** - 提出疑问或建议
5. **决定状态**
   - Approve - 同意合并
   - Request Changes - 需要修改
   - Comment - 仅评论

### 对于作者

1. **响应评论** - 及时回复审查意见
2. **修改代码** - 根据反馈修改
3. **解释说明** - 说明设计决策
4. **重新请求审查** - 修改后请求再次审查

## 评论规范

### 好的评论示例

**提问式：**
```
这里的循环是否可以用 map 替代，提高可读性？
```

**建议式：**
```
建议添加空值检查，防止 NPE：
```java
if (user == null) {
    throw new UserNotFoundException();
}
```
```

**解释式：**
```
这个常量的值为什么是 1000？建议添加注释说明。
```

### 避免的评论

**过于简单：**
```
不好。
```

**过于主观：**
```
我不喜欢这种写法。
```

**人身攻击：**
```
你怎么能写出这种代码？
```

## 常见问题和解决方案

### 代码风格不一致

**问题：** 代码风格与项目规范不符

**解决方案：**
```
请运行代码格式化工具：
- 前端: pnpm lint:fix
- 后端: mvn spotbugs:check
- Python: ruff format .
```

### 缺少测试

**问题：** 新功能没有测试

**解决方案：**
```
建议为这个功能添加单元测试，覆盖以下场景：
1. 正常情况
2. 边界情况
3. 错误情况
```

### 性能问题

**问题：** 代码有性能隐患

**解决方案：**
```
这里的查询可能在数据量大时变慢。建议：
1. 添加索引
2. 使用分页
3. 添加缓存
```

## 审查工具

### GitHub 功能

- **行内评论** - 在特定代码行添加评论
- **建议修改** - 直接建议代码修改
- **审查状态** - 标记审查完成状态
- **检查列表** - 使用 PR 模板中的检查项

### 本地工具

```bash
# 前端
pnpm lint
pnpm tsc
pnpm test

# 后端
mvn spotbugs:check
mvn test

# Python
ruff check .
pytest
```

## 合并标准

PR 满足以下条件可以合并：

- [ ] 至少 1 个维护者批准
- [ ] 所有 CI 检查通过
- [ ] 没有未解决的审查意见
- [ ] 分支已更新到最新
- [ ] 提交历史清晰

## 紧急情况

对于紧急修复：

1. 标记 PR 为 `urgent`
2. 简化审查流程
3. 事后补充测试和文档

## 学习资源

- [Google 代码审查指南](https://google.github.io/eng-practices/review/)
- [Phabricator 审查指南](https://secure.phabricator.com/book/phabflavor/article/reviews/)
