代码整洁之道

应力求简洁、直接、聚焦解决方案。整洁的代码读起来应如优美的散文——每个名称都揭示意图，每个函数只做一件事，每个抽象都有其存在的价值。

安装

OpenClaw / Moltbot / Clawbot

npx clawhub@latest install clean-code

核心原则

命名规则

名称是最重要的文档。一个好的名字无需注释。

规则：如果需要注释来解释一个名称，请重命名它。

命名反模式

函数规则

卫语句

用提前返回来展平嵌套条件，嵌套深度不超过2层

// BAD — 5 levels deep
function processOrder(order: Order) {
  if (order) {
    if (order.items.length > 0) {
      if (order.customer) {
        if (order.customer.isVerified) {
          return submitOrder(order);
        }
      }
    }
  }
  throw new Error('Invalid order');
}

// GOOD — guard clauses flatten the structure
function processOrder(order: Order) {
  if (!order) throw new Error('No order');
  if (!order.items.length) throw new Error('No items');
  if (!order.customer) throw new Error('No customer');
  if (!order.customer.isVerified) throw new Error('Customer not verified');

  return submitOrder(order);
}

参数对象

当函数需要超过3个参数时，使用配置对象

// BAD — too many parameters, order matters
createUser('John', 'Doe', 'john@example.com', 'secret', 'admin', 'Engineering');

// GOOD — self-documenting options object
createUser({
  firstName: 'John',
  lastName: 'Doe',
  email: 'john@example.com',
  password: 'secret',
  role: 'admin',
  department: 'Engineering',
});

代码结构模式

组合优于全能函数

// BAD — god function doing everything
async function processOrder(order: Order) {
  // Validate... (15 lines)
  // Calculate totals... (15 lines)
  // Process payment... (10 lines)
  // Send notifications... (10 lines)
  // Update inventory... (10 lines)
  return { success: true };
}

// GOOD — composed of small, focused functions
async function processOrder(order: Order) {
  validateOrder(order);
  const totals = calculateOrderTotals(order);
  const payment = await processPayment(order.customer, totals);
  await sendOrderConfirmation(order, payment);
  await updateInventory(order.items);
  return { success: true, orderId: payment.orderId };
}

返回类型一致性

函数应返回一致的类型。对于多个结果，使用可辨识联合。

// BAD — returns different types
function getUser(id: string) {
  const user = database.find(id);
  if (!user) return false;     // boolean
  if (user.isDeleted) return null; // null
  return user;                 // User
}

// GOOD — discriminated union
type GetUserResult =
  | { status: 'found'; user: User }
  | { status: 'not_found' }
  | { status: 'deleted' };

function getUser(id: string): GetUserResult {
  const user = database.find(id);
  if (!user) return { status: 'not_found' };
  if (user.isDeleted) return { status: 'deleted' };
  return { status: 'found', user };
}

反模式

编辑前安全检查

在更改任何文件之前，回答这些问题以避免连锁破坏：

File to edit: UserService.ts
├── Who imports this? → UserController.ts, AuthController.ts
├── Do they need changes too? → Check function signatures
└── What tests cover this? → UserService.test.ts

规则：在同一任务中编辑文件及所有依赖文件。切勿遗留损坏的导入或缺失的更新。

完成前自检

在标记任何任务完成前，请验证：

绝对不要

1. 绝对不要添加仅重复代码内容的注释——如果代码需要注释来解释其功能，那就重命名直到无需注释为止
2. 绝对不要为少于3个用例创建抽象——过早抽象比重复代码更糟糕
3. 绝对不要在代码库中留下被注释掉的代码——直接删除；版本控制系统就是用来记录历史的
4. 绝对不要编写超过20行的函数——提取子函数，直到每个函数只做一件事
5. 绝对不要让嵌套深度超过2层——使用保护子句、提前返回或提取函数
6. 绝对不要使用魔法数字或字符串——定义具有清晰语义的命名常量
7. 绝对不要在不检查其依赖关系的情况下编辑文件——在多文件变更中，导入中断和更新缺失是最常见的错误来源
8. 绝不要留下未通过代码检查或类型检查的任务—— 在标记完成之前修复所有错误

参考资料

关于特定整洁代码主题的详细指南：