TypeScript 清洁代码实践指南 - 来自 lcomment/development-recipes 的经验总结

前言

在软件开发中，编写可维护、可读性高的代码是每个开发者都应该追求的目标。本文将基于 lcomment/development-recipes 项目中的 TypeScript 清洁代码实践，分享一些实用的编码规范和技巧。

变量命名规范

命名风格统一

在团队协作中，保持一致的命名风格至关重要。TypeScript 社区通常推荐以下风格：

• camelCase：变量和函数命名（如 userName）
• PascalCase：类和类型命名（如 UserProfile）
• UPPER_CASE：常量命名（如 MAX_COUNT）

有意义的变量名

// 不好的实践
const d = 86400000; // 这个数字代表什么？

// 好的实践
const MILLISECONDS_IN_A_DAY = 24 * 60 * 60 * 1000;

关键点：

• 避免使用魔法数字
• 变量名应能清晰表达其用途
• 使用可搜索的名称（避免缩写除非是广泛认可的）

枚举(Enum)的最佳实践

TypeScript 的枚举类型非常适合为一组相关常量提供有意义的名称：

enum MediaType {
  VIDEO = "video",
  AUDIO = "audio",
  IMAGE = "image"
}

function processMedia(mediaType: MediaType) {
  switch(mediaType) {
    case MediaType.VIDEO:
      // 处理视频逻辑
      break;
    case MediaType.AUDIO:
      // 处理音频逻辑
      break;
  }
}

优势：

• 提高代码可读性
• 减少拼写错误
• 便于类型检查

函数设计原则

单一职责原则

每个函数应该只做一件事，并且做好这件事：

// 不好的实践：函数做太多事情
function processUserData(user: User) {
  validateUser(user);
  saveToDatabase(user);
  sendWelcomeEmail(user);
  updateAnalytics(user);
}

// 好的实践：拆分职责
function handleNewUserRegistration(user: User) {
  validateUser(user);
  const savedUser = saveUserToDatabase(user);
  notifyUser(savedUser);
  trackRegistration(savedUser);
}

参数处理技巧

1. 限制参数数量：理想情况下不超过2个参数
2. 使用对象参数：当需要多个参数时

// 不好的实践：多个参数
function createPost(title: string, content: string, author: string, date: Date, tags: string[]) {
  // ...
}

// 好的实践：使用参数对象
interface PostOptions {
  title: string;
  content: string;
  author: string;
  date: Date;
  tags: string[];
}

function createPost(options: PostOptions) {
  // ...
}

3. 默认参数：简化条件判断

// 不好的实践
function fetchData(limit?: number) {
  const actualLimit = limit !== undefined ? limit : 10;
  // ...
}

// 好的实践
function fetchData(limit: number = 10) {
  // ...
}

类设计原则

单一职责原则(SRP)

一个类应该只有一个引起它变化的原因：

// 不好的实践：承担太多职责
class UserManager {
  authenticate() { /*...*/ }
  sendEmail() { /*...*/ }
  logActivity() { /*...*/ }
  generateReport() { /*...*/ }
}

// 好的实践：职责分离
class Authenticator {
  authenticate() { /*...*/ }
}

class Notifier {
  sendEmail() { /*...*/ }
}

class ActivityLogger {
  logActivity() { /*...*/ }
}

class ReportGenerator {
  generateReport() { /*...*/ }
}

高内聚低耦合

高内聚：类的方法应该主要操作类的属性 低耦合：类之间的依赖应该最小化

// 不好的实践：低内聚高耦合
class OrderProcessor {
  constructor(
    private db: Database,
    private emailService: EmailService,
    private paymentGateway: PaymentGateway
  ) {}

  processOrder() {
    // 处理订单逻辑
    // 发送邮件
    // 处理支付
  }
}

// 好的实践：高内聚低耦合
class OrderService {
  constructor(private db: Database) {}

  processOrder() {
    // 只处理订单核心逻辑
  }
}

class NotificationService {
  constructor(private emailService: EmailService) {}

  sendOrderConfirmation() {
    // 处理邮件发送
  }
}

class PaymentService {
  constructor(private paymentGateway: PaymentGateway) {}

  processPayment() {
    // 处理支付逻辑
  }
}

避免代码重复

重复代码是维护的噩梦，遵循DRY(Don't Repeat Yourself)原则：

// 不好的实践：重复逻辑
function calculateTotal(items: Item[]) {
  let total = 0;
  for (const item of items) {
    total += item.price * item.quantity;
  }
  return total;
}

function calculateTax(items: Item[]) {
  let subtotal = 0;
  for (const item of items) {
    subtotal += item.price * item.quantity;
  }
  return subtotal * 0.1;
}

// 好的实践：提取公共逻辑
function calculateSubtotal(items: Item[]) {
  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
}

function calculateTotal(items: Item[]) {
  return calculateSubtotal(items);
}

function calculateTax(items: Item[]) {
  return calculateSubtotal(items) * 0.1;
}

总结

编写清洁的TypeScript代码需要遵循以下核心原则：

1. 命名清晰：使用有意义的名称，保持风格一致
2. 函数精简：单一职责，参数简洁
3. 类设计合理：高内聚低耦合，职责单一
4. 避免重复：遵循DRY原则
5. 合理使用类型系统：充分利用TypeScript的类型特性

通过实践这些原则，你的代码将变得更易读、更易维护，团队协作效率也会显著提高。记住，清洁代码不是一次性的工作，而是需要持续关注和改进的过程。