二、代码审查（Code Review）
2.1 Code Review 的目标
2.2 提交 PR 的最佳实践
# PR 标题格式
[类型] 简短描述
类型：
- feat: 新功能
- fix: Bug 修复
- docs: 文档
- style: 格式
- refactor: 重构
- test: 测试
- chore: 构建/工具
示例：
[feat] 添加用户登录功能
[fix] 修复购物车数量计算错误
[docs] 更新 API 文档
# PR 描述模板
## 变更内容
- 添加了用户登录接口
- 增加了 JWT 认证中间件
## 变更原因
用户反馈需要保持登录状态
## 影响范围
- 影响所有需要认证的接口
- 需要更新前端 token 存储逻辑
## 测试情况
- [x] 单元测试通过
- [x] 集成测试通过
- [x] 手动测试正常
## 截图（如适用）
[附上界面变化截图]
## 关联 Issue
Closes #123
Related #456
2.3 Review 时的检查清单
## 功能检查
- [ ] 代码是否实现了需求描述的所有功能？
- [ ] 边界情况是否处理了？（空值、极限值、异常情况）
- [ ] 错误处理是否完善？
## 代码质量
- [ ] 命名是否清晰？
- [ ] 函数是否足够短？（不超过 50 行）
- [ ] 是否有重复代码？
- [ ] 是否有过深的嵌套？（不超过 3 层）
## 性能
- [ ] 是否有不必要的循环？
- [ ] 数据库查询是否有索引？
- [ ] 是否有内存泄漏风险？
## 安全
- [ ] 是否有 SQL 注入风险？
- [ ] 是否有 XSS 风险？
- [ ] 敏感信息是否加密？
- [ ] 权限检查是否到位？
## 测试
- [ ] 是否有单元测试？
- [ ] 关键路径是否有测试覆盖？
## 文档
- [ ] 是否需要更新 README？
- [ ] 复杂逻辑是否有注释？
- [ ] API 变更是否有文档？
2.4 Review 评论的艺术
# ❌ 不好的评论
“这个写法不对”
“为什么要这样写？”
“太乱了”
# ✅ 好的评论
## 指出问题 + 给出理由
“这里直接用 setTimeout 可能会有问题，因为组件卸载时没有清理，可能导致内存泄漏。”
## 提出建议 + 示例
“建议把这个重复的逻辑提取成公共函数，比如：
function formatDate(date) {
return moment(date).format('YYYY-MM-DD');
}
”
## 提出疑问 + 开放讨论
“这里用 Map 而不是 Object 是有什么特殊考虑吗？还是单纯个人习惯？”
## 肯定好的部分
“这个边界情况的处理很周到！”
“抽象成 hooks 后，逻辑清晰了很多！”
## 标记非阻塞性建议
“非阻塞：可以考虑把这个常量移到单独的配置文件，这样更好维护。”
2.5 被 Review 的心态
# ✅ 正确的心态
1. Review 的是代码，不是你这个人
2. 每个评论都是一个学习机会
3. 提出疑问不是质疑你的能力
# 如何回应评论
## 同意 → 修改 + 回复
“好的，已修改，请查看。”
## 不同意 → 解释理由
“这里我考虑过用 A 方案，但选择 B 是因为性能更好。可以用 benchmark 验证。”
## 需要讨论 → 约个短会
“这个问题比较复杂，我们花 5 分钟同步一下？”
三、文档编写
3.1 README 的结构
# 项目名称
一句话描述项目是干什么的
## 徽章（可选）
## 功能特性
- 功能点 1
- 功能点 2
- 功能点 3
## 技术栈
- 语言/框架/库
## 快速开始
### 环境要求
- Node.js >= 18
- MySQL >= 8.0
### 安装
```bash
git clone https://github.com/xxx/repo.git
cd repo
npm install
配置
cp .env.example .env
# 编辑 .env 配置
运行
npm run dev
测试
npm test
API 文档
项目结构
src/
├── components/ # UI 组件
├── pages/ # 页面
├── services/ # 业务逻辑
├── utils/ # 工具函数
└── types/ # 类型定义
如何贡献
Fork 本仓库
创建特性分支 (git checkout -b feature/xxx)
提交更改 (git commit -m 'feat: add xxx')
推送到分支 (git push origin feature/xxx)
提交 Pull Request
许可证
MIT
### 3.2 代码中的文档
```javascript
// 好的注释 = 解释“为什么”，而不是“是什么”
// ❌ 无用的注释
// 设置 name 为张三
let name = '张三';
// ✅ 有用的注释
// 使用硬编码的测试账号，因为登录功能还在开发中
const TEST_USER_NAME = 'test_user';
// ❌ 注释过时
// 使用旧 API v1
// fetch('/api/v1/users')
// ✅ 删除过时代码，不要注释掉
3.3 变更日志（CHANGELOG）
# Changelog
## [1.2.0] - 2024-01-15
### Added
- 新增用户头像上传功能
- 新增暗色主题支持
### Changed
- 优化首页加载性能，首屏时间减少 30%
- 升级 React 到 18.2.0
### Fixed
- 修复移动端菜单点击无响应的问题
- 修复用户登录后偶发性白屏
### Deprecated
- `oldLogin` 方法将在下个版本移除，请使用 `newLogin`
### Security
- 修复了 XSS 漏洞（CVE-2024-12345）
## [1.1.0] - 2024-01-01
### Added
- 添加用户注册功能
- 添加密码重置功能
### Fixed
- 修复邮件发送超时问题
