注释

// ❌ 冗余注释
// 将计数器加 1
counter++;

// ❌ 过时注释（代码已更改，注释未更新）
// 返回用户的全名
function getUserEmail(user: User) {
  return user.email;
}

// ✅ 解释“为什么”，而不是“是什么”
// 使用二分查找，因为列表已排序且可能包含超过 10 万个项目
const index = binarySearch(sortedItems, target);

// ✅ 警告不明显的行为
// 重要提示：此函数出于性能原因会修改输入数组
function quickSort(arr: number[]): number[] {
  // ...
}

// ✅ 带上下文的 TODO
// TODO(john): 迁移完成后移除 - 在 JIRA-1234 中跟踪
const legacyAdapter = new LegacyAdapter();

SOLID 原则

单一职责原则

// ❌ 多个职责
class UserManager {
  createUser(data: UserData) { /* DB logic */ }
  validateEmail(email: string) { /* Validation logic */ }
  sendWelcomeEmail(user: User) { /* Email logic */ }
  generateReport(users: User[]) { /* Report logic */ }
}

// ✅ 每个类单一职责
class UserRepository {
  create(data: UserData): User { /* DB logic */ }
  findById(id: string): User | null { /* DB logic */ }
}

class UserValidator {
  validateEmail(email: string): boolean { /* Validation */ }
  validatePassword(password: string): ValidationResult { /* Validation */ }
}

class EmailService {
  sendWelcomeEmail(user: User): void { /* Email logic */ }
}

class UserReportGenerator {
  generate(users: User[]): Report { /* Report logic */ }
}

开闭原则

// ❌ 必须修改代码才能添加新的支付方式
class PaymentProcessor {
  process(payment: Payment) {
    if (payment.type === 'credit') {
      // Credit card logic
    } else if (payment.type === 'paypal') {
      // PayPal logic
    } else if (payment.type === 'crypto') {
      // Crypto logic - had to modify existing code!
    }
  }
}

// ✅ 对扩展开放，对修改封闭
interface PaymentMethod {
  process(amount: number): Promise<PaymentResult>;
}

class CreditCardPayment implements PaymentMethod {
  async process(amount: number): Promise<PaymentResult> { /* ... */ }
}

class PayPalPayment implements PaymentMethod {
  async process(amount: number): Promise<PaymentResult> { /* ... */ }
}

// 新的支付方式 - 无需修改现有代码
class CryptoPayment implements PaymentMethod {
  async process(amount: number): Promise<PaymentResult> { /* ... */ }
}

class PaymentProcessor {
  constructor(private method: PaymentMethod) {}

  async process(amount: number): Promise<PaymentResult> {
    return this.method.process(amount);
  }
}

里氏替换原则

// ❌ 违反 LSP - Square 破坏了 Rectangle 的约定
class Rectangle {
  constructor(public width: number, public height: number) {}

  setWidth(w: number) { this.width = w; }
  setHeight(h: number) { this.height = h; }
  getArea() { return this.width * this.height; }
}

class Square extends Rectangle {
  setWidth(w: number) {
    this.width = w;
    this.height = w; // 意外的副作用！
  }
  setHeight(h: number) {
    this.width = h;
    this.height = h; // 意外的副作用！
  }
}

// ✅ 正确的抽象
interface Shape {
  getArea(): number;
}

class Rectangle implements Shape {
  constructor(private width: number, private height: number) {}
  getArea() { return this.width * this.height; }
}

class Square implements Shape {
  constructor(private side: number) {}
  getArea() { return this.side * this.side; }
}

接口隔离原则

// ❌ 臃肿的接口
interface Worker {
  work(): void;
  eat(): void;
  sleep(): void;
  attendMeeting(): void;
  writeReport(): void;
}

// 机器人不能吃或睡！
class Robot implements Worker {
  work() { /* ... */ }
  eat() { throw new Error('Robots do not eat'); }  // 被迫实现
  sleep() { throw new Error('Robots do not sleep'); }
  // ...
}

// ✅ 分离的接口
interface Workable {
  work(): void;
}

interface Eatable {
  eat(): void;
}

interface Sleepable {
  sleep(): void;
}

class Human implements Workable, Eatable, Sleepable {
  work() { /* ... */ }
  eat() { /* ... */ }
  sleep() { /* ... */ }
}

class Robot implements Workable {
  work() { /* ... */ }
}

依赖倒置原则

// ❌ 高层模块依赖于低层模块
class OrderService {
  private db = new MySQLDatabase();  // 具体依赖
  private mailer = new SendGridMailer();  // 具体依赖

  createOrder(data: OrderData) {
    const order = this.db.insert('orders', data);
    this.mailer.send(data.email, 'Order confirmed');
    return order;
  }
}

// ✅ 依赖于抽象
interface Database {
  insert(table: string, data: unknown): unknown;
  find(table: string, query: unknown): unknown[];
}

interface Mailer {
  send(to: string, message: string): void;
}

class OrderService {
  constructor(
    private db: Database,
    private mailer: Mailer
  ) {}

  createOrder(data: OrderData) {
    const order = this.db.insert('orders', data);
    this.mailer.send(data.email, 'Order confirmed');
    return order;
  }
}

// 现在我们可以注入任何实现
const service = new OrderService(
  new PostgresDatabase(),
  new SESMailer()
);

代码审查最佳实践

审查要点

## 代码审查清单

### 正确性
- [ ] 逻辑正确且处理了边界情况
- [ ] 错误处理得当
- [ ] 没有明显的错误或回归

### 设计
- [ ] 代码处于正确的抽象层次
- [ ] 没有不必要的复杂性
- [ ] 遵循代码库中现有的模式

### 可读性
- [ ] 命名清晰，意图明确
- [ ] 注释解释“为什么”而不是“是什么”
- [ ] 代码尽可能做到自文档化

### 测试
- [ ] 测试覆盖率足够
- [ ] 测试有意义（不仅仅是凑覆盖率）
- [ ] 测试了边界情况

### 性能
- [ ] 没有明显的 N+1 查询或低效操作
- [ ] 使用了合适的数据结构
- [ ] 如果需要，考虑了缓存

### 安全性
- [ ] 有输入验证
- [ ] 代码中没有密钥
- [ ] 认证/授权正确

提供反馈

# 良好的审查评论

## ✅ 具体且可操作
"这个循环的复杂度是 O(n²)。考虑使用 Map 来实现 O(n) 的查找。"

## ✅ 解释原因
"让我们把这个提取到一个单独的函数中 - 这样可以使逻辑更容易测试，主函数也更易读。"

## ✅ 提供替代方案
"与其修改数组，考虑使用 `filter()`，它会返回一个新数组：`const active = items.filter(i => i.active)`"

## ✅ 区分严重程度
- "nit: " - 次要的风格问题，可选
- "suggestion: " - 最好有，但不阻塞
- "blocking: " - 必须在合并前修复

# 避免

## ❌ 模糊的批评
"这段代码很混乱"

## ❌ 人身攻击
"你总是犯这个错误"

## ❌ 没有解释
"用不同的方法"

代码度量

圈复杂度

// 高复杂度 (10+) - 难以测试和维护
function processOrder(order: Order): Result {
  if (order.status === 'pending') {           // +1
    if (order.paymentMethod === 'card') {     // +1
      if (order.amount > 1000) {              // +1
        // ...
      } else if (order.amount > 100) {        // +1
        // ...
      } else {
        // ...
      }
    } else if (order.paymentMethod === 'cash') {  // +1
      // ...
    }
  } else if (order.status === 'processing') {  // +1
    // ...
  }
  // ... 更多分支
}

// 低复杂度 - 提取条件
function processOrder(order: Order): Result {
  const processor = getProcessor(order.paymentMethod);
  const tier = getPricingTier(order.amount);
  return processor.process(order, tier);
}

需要跟踪的指标

代码检查与格式化

ESLint 配置

// .eslintrc.js
module.exports = {
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended',
  ],
  rules: {
    // 防止错误
    'no-unused-vars': 'error',
    '@typescript-eslint/no-floating-promises': 'error',
    '@typescript-eslint/no-misused-promises': 'error',

    // 代码质量
    'complexity': ['warn', 10],
    'max-lines-per-function': ['warn', 50],
    'max-depth': ['warn', 3],

    // 一致性
    'prefer-const': 'error',
    'no-var': 'error',
  }
};

预提交钩子

// package.json
{
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  "lint-staged": {
    "*.{ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{json,md}": [
      "prettier --write"
    ]
  }
}

相关技能

• [[refactoring]] - 改进现有代码
• [[testing-strategies]] - 通过测试确保质量
• [[design-patterns]] - 经过验证的解决方案

Sharp Edges（常见陷阱）

这些是代码质量中最常见且代价最高的错误

SE-1: 过度工程 (Over-engineering)

• 严重度 : high
• 情境 : 为了“未来可能需要”而增加不必要的抽象和复杂度
• 原因 : YAGNI 原则被忽视、设计模式滥用、“万一以后要...”的心态
• 症状 :
  • 简单功能需要改动 10+ 个文件
  • 新人看不懂架构
  • 代码比需求复杂 10 倍
• 检测 : Factory.*Factory|Abstract.*Abstract|interface.*\{.*\}(?=.*interface.*\{.*\})|Strategy.*Strategy
• 解法 : YAGNI（You Aren't Gonna Need It）、先写最简单的实现、需要时再重构

SE-2: 命名不一致

• 严重度 : medium
• 情境 : 同一个概念在不同地方用不同名称，或不同概念用相似名称
• 原因 : 没有统一术语、多人开发没有对齐、复制粘贴没改名
• 症状 :
  • user, customer, client, account 指同一件事
  • 搜索不到相关代码
  • 新人经常问“这个和那个有什么区别？”
• 检测 : (user|customer|client|account).*=.*find|(get|fetch|retrieve|load).*User
• 解法 : 建立术语表（Ubiquitous Language）、Code Review 时检查命名、重构统一命名

SE-3: 深层嵌套 (Deep Nesting)

• 严重度 : medium
• 情境 : if-else 或 callback 嵌套超过 3-4 层，难以阅读
• 原因 : 没有提早 return、没有抽取函数、callback hell
• 症状 :
  • 需要横向滚动才能看到代码
  • 很难追踪哪个 } 对应哪个 {
  • Cyclomatic complexity 超高
• 检测 : \{.*\{.*\{.*\{|if.*if.*if.*if|\.then\(.*\.then\(.*\.then\(
• 解法 : Guard clause（提早 return）、抽取函数、使用 async/await 取代 callback

SE-4: 神奇数字/字符串 (Magic Numbers)

• 严重度 : medium
• 情境 : 代码中直接使用意义不明的数字或字符串
• 原因 : 懒得定义常量、“只用一次不用抽出来”
• 症状 :
  • 看到 86400 不知道是什么（一天的秒数）
  • 修改时需要全局搜索 replace
  • 同一个数字在不同地方意义不同但值相同
• 检测 : \b(86400|3600|1000|60000|1024|65535)\b|status\s*===?\s*['"][^'"]+['"]
• 解法 : 抽取为有意义名称的常量、使用 enum、集中管理设定值

SE-5: 大泥球 (Big Ball of Mud)

• 严重度 : critical
• 情境 : 代码没有明确架构，所有东西混在一起，到处都有依赖
• 原因 : 没有模块化设计、赶时间“先 work 再说”、缺乏重构
• 症状 :
  • 改 A 会坏 B
  • 单一文件 1000+ 行
  • 所有东西都 import 所有东西
• 检测 : import.*from.*\.\.\/\.\.\/\.\.\/|require\(.*\.\..*\.\..*\.\.\)|lines.*>\s*1000
• 解法 : 分层架构、明确的模块边界、定期重构、严格的 import 规则

Validations

V-1: 禁止 console.log (生产代码)

• 类型 : regex
• 严重度 : medium
• 模式 : console\.(log|debug|info)\(
• 消息 : console.log should not be in production code
• 修复建议 : Use a proper logger (winston, pino) or remove debug statements
• 适用 : *.ts, *.js

V-2: 禁止 any 类型

• 类型 : ast
• 严重度 : high
• 模式 : TSAnyKeyword
• 消息 : 'any' type defeats TypeScript's type safety
• 修复建议 : Use specific type, 'unknown', or generic type parameter
• 适用 : *.ts, *.tsx

V-3: 函数参数过多

• 类型 : regex
• 严重度 : medium
• 模式 : function\s+\w+\s*\([^)]*,\s*[^)]*,\s*[^)]*,\s*[^)]*,\s*[^)]*\)|=>\s*\([^)]*,\s*[^)]*,\s*[^)]*,\s*[^)]*,\s*[^)]*\)
• 消息 : Function has more than 4 parameters - consider using an object
• 修复建议 : Replace multiple params with single options object: function(options: Options)
• 适用 : *.ts, *.js

V-4: TODO 无追踪

• 类型 : regex
• 严重度 : low
• 模式 : //\s*TODO(?!.*#\d|.*JIRA|.*\w+-\d+)
• 消息 : TODO comment without tracking reference
• 修复建议 : Add issue reference: // TODO(#123): description or create ticket
• 适用 : *.ts, *.js, *.tsx, *.jsx

V-5: 深层 import 路径

• 类型 : regex
• 严重度 : medium
• 模式 : import.*from\s+['"]\.\.\/\.\.\/\.\.\/|require\s*\(\s*['"]\.\.\/\.\.\/\.\.\/
• 消息 : Deep relative imports indicate poor module boundaries
• 修复建议 : Use path aliases: import { X } from '@/modules/x'
• 适用 : *.ts, *.js, *.tsx, *.jsx

Weekly Installs

177

Repository

miles990/claude…e-skills

GitHub Stars

7

First Seen

Jan 24, 2026

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

opencode170

gemini-cli164

codex163

github-copilot159

cursor156

kimi-cli137