代码基础审查 fundamentals-gate

---

名称：基础检查门 描述：验证代码质量，包括命名规范、函数大小和DRY原则。在/own:done流程中提供抛光项目的建议门。

门 5: 基础审查

“好代码不仅仅是能工作的代码。它是其他人也能使用的代码。”

目的

这个门根据工程标准检查通用代码质量。问题是建议，不是阻碍 — 它们是抛光，不是问题。

门状态

• 通过 — 代码质量扎实
• 建议 — 推荐小改进

---

门问题

问题 1: 命名清晰度

“新开发者能仅从名称理解[变量/函数]的作用吗？”

寻找：

• 描述性、意图揭示的名称
• 无缩写或单字母
• 布尔前缀（是、有、能）
• 函数动词（获取、设置、处理）

问题 2: 函数专注

“你能用一句话描述这个函数做什么而不使用’和’吗？”

寻找：

• 单一职责
• 合理大小（30行以下）
• 清晰的输入/输出关系
• 无隐藏副作用

问题 3: 代码重用

“我在几个地方看到这个模式。是故意重复还是应该提取？”

寻找：

• 意识到重复
• 适当的抽象（三次规则）
• 不为一次性使用过度工程

---

基础检查表

命名

• [ ] 变量是描述性的（无临时、数据、x）
• [ ] 布尔前缀有是、有、能、应该
• [ ] 函数以动词开头
• [ ] 无不必要的缩写
• [ ] 一致的命名模式

函数

• [ ] 单一职责
• [ ] 30行以下（一般）
• [ ] 少于4个参数
• [ ] 早期返回而不是深层嵌套
• [ ] 无魔数（使用命名常量）

结构

• [ ] 相关代码分组在一起
• [ ] 适当的文件组织
• [ ] 清晰的关注点分离
• [ ] 一致的格式化

注释

• [ ] 解释为什么，而不是什么
• [ ] 无注释掉的代码（删除它）
• [ ] 无明显的注释（// 增加计数器）
• [ ] 复杂逻辑有文档

---

响应模板

如果通过

✅ 基础检查门：通过

代码质量扎实：
- 命名清晰一致
- 函数专注
- 整体结构良好

所有门通过！让我们进入代码审查...

如果有建议

💡 基础检查门：建议

一些抛光项目供考虑：

**建议 1: [命名]**
`const d = new Date()` → `const createdAt = new Date()`
为什么：描述性名称帮助未来读者

**建议 2: [函数大小]**
`processOrder()` 是80行。考虑拆分为：
- `validateOrder()`
- `calculateTotal()`
- `saveOrder()`

**建议 3: [魔数]**
`if (status === 2)` → `if (status === STATUS.ACTIVE)`
为什么：命名常量是自文档化的

这些是建议，不是阻碍。代码有效 — 这是关于抛光。
进行代码审查？还是先处理这些？

---

常见问题检查

1. 不清晰的命名

❌ const d = new Date();
   const temp = getUser();
   const flag = true;

✅ const createdAt = new Date();
   const currentUser = getUser();
   const isAuthenticated = true;

2. 魔数

❌ if (status === 2) { ... }
   setTimeout(fn, 86400000);

✅ const STATUS = { ACTIVE: 2, INACTIVE: 1 };
   if (status === STATUS.ACTIVE) { ... }

   const ONE_DAY_MS = 24 * 60 * 60 * 1000;
   setTimeout(fn, ONE_DAY_MS);

3. 深层嵌套

❌ function check(user) {
     if (user) {
       if (user.active) {
         if (user.role === 'admin') {
           return true;
         }
       }
     }
     return false;
   }

✅ function check(user) {
     if (!user) return false;
     if (!user.active) return false;
     if (user.role !== 'admin') return false;
     return true;
   }

4. 上帝函数

❌ function processOrder(order) {
     // 100+行验证、计算、保存、发送邮件...
   }

✅ function processOrder(order) {
     validateOrder(order);
     const total = calculateTotal(order);
     await saveOrder(order, total);
     await sendConfirmation(order);
   }

5. 无意义的注释

❌ // 增加计数器
   counter++;

   // 获取用户
   const user = getUser();

✅ // 速率限制：每个用户每分钟最多100个请求
   if (requestCount >= 100) {
     throw new RateLimitError();
   }

---

苏格拉底式基础问题

而不是指出修复，问：

1. “d代表什么？新开发者会知道吗？”
2. “数字2在这个上下文中意味着什么？”
3. “你能不用’和’描述这个函数吗？”
4. “我看到这个模式三次 — 是故意的吗？”
5. “六个月后你会理解这个注释吗？”

---

标准参考

查看详细模式：

• /standards/global/naming-conventions.md
• /standards/global/error-handling.md
• /standards/frontend/component-architecture.md

---

命名快速参考

类型	模式	示例
变量	驼峰式，描述性	userEmail, isLoading
布尔	是/有/能/应该前缀	isActive, hasPermission
函数	动词 + 名词	getUser(), handleSubmit()
常量	大写蛇形命名法	MAX_RETRIES, API_URL
类	帕斯卡命名法	UserService, ApiClient

---

何时跳过建议

不是每个建议都需要处理：

• 原型代码 — 抛光可以等待
• 时间压力 — 先发布工作代码，抛光稍后
• 最小影响 — 如果只是风格偏好
• 现有模式 — 匹配代码库约定，即使不完美

基础是关于成长，不是完美。记录建议以学习，但不阻碍发布。