// 差：用注释解释糟糕的代码
// 检查用户是否满足活跃条件
// 活跃条件：最近30天内有登录记录
if (user.getLastLoginDate() != null && 
    user.getLastLoginDate().isAfter(LocalDate.now().minusDays(30))) {
  // ...
}

// 好：重构代码使其自解释
private static final int ACTIVE_THRESHOLD_DAYS = 30;

if (isUserActive(user)) {
  // ...
}

private boolean isUserActive(User user) {
  if (user.getLastLoginDate() == null) {
    return false;
  }
  return user.getLastLoginDate().isAfter(
      LocalDate.now().minusDays(ACTIVE_THRESHOLD_DAYS));
}

// 版权和许可信息是必要的
/*
 * Copyright 2024 Example Corp. All rights reserved.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 */

// 解释代码背后的决策或业务规则
// 由于历史原因，活跃用户的阈值是30天
// 而不是行业标准的90天
private static final int ACTIVE_THRESHOLD_DAYS = 30;

// 解释不直观的算法
// 使用位运算检查权限，每个bit代表一种权限
// bit 0: READ, bit 1: WRITE, bit 2: DELETE
public boolean hasPermission(int permissions, Permission permission) {
  return (permissions & (1 << permission.ordinal())) != 0;
}

// 解释"为什么"而非"做什么"
// 使用 synchronized 而非 ReentrantLock
// 因为这里的竞争不激烈，synchronized 性能更好
public synchronized void incrementCounter() {
  counter++;
}

// 警告其他程序员注意的陷阱
// WARNING: 这个方法不是线程安全的
// 如果在多线程环境中使用，需要外部同步
public void processOrder(Order order) {
  // ...
}

// 差：注释重复了代码
// 获取用户名称
String name = user.getName();

// 差：注释解释了显而易见的代码
// 循环遍历所有订单
for (Order order : orders) {
  // ...
}

// 差：注释与代码不一致
// 计算税费（实际没有计算税费）
double total = subtotal + shipping;
// 注释说"计算税费"，但代码没有计算税费

// 差：注释掉的代码
public void processOrder(Order order) {
  // double discount = calculateDiscount(order);
  // if (discount > 0) {
  //   order.setDiscount(discount);
  // }
  order.setTotal(calculateTotal(order));
}

// 好：删除注释掉的代码，用版本控制追踪历史
public void processOrder(Order order) {
  order.setTotal(calculateTotal(order));
}

// 差：用注释解释
// 检查员工是否有资格获得奖金
// 条件：工作超过5年且绩效评分超过8
if (employee.getYearsOfService() > 5 && employee.getPerformanceRating() > 8) {
  // ...
}

// 好：用方法名表达
if (employee.isEligibleForBonus()) {
  // ...
}

private boolean isEligibleForBonus() {
  return yearsOfService > 5 && performanceRating > 8;
}

// 差：用注释解释复杂逻辑
// 如果是VIP客户，折扣20%
// 如果是普通客户，折扣10%
// 如果是新客户，没有折扣
double discount;
if (customer.isVip()) {
  discount = 0.2;
} else if (customer.isRegular()) {
  discount = 0.1;
} else {
  discount = 0;
}

// 好：用策略模式
public interface DiscountStrategy {
  double calculateDiscount(Customer customer);
}

public class VipDiscountStrategy implements DiscountStrategy {
  @Override
  public double calculateDiscount(Customer customer) {
    return 0.2;
  }
}

// 使用
DiscountStrategy strategy = discountStrategyFactory.getStrategy(customer);
double discount = strategy.calculateDiscount(customer);

/**
 * 计算订单的总价，包括商品金额、折扣、税费和运费。
 *
 * @param order 要计算的订单，不能为 null
 * @return 订单总价，永远不为 null
 * @throws IllegalArgumentException 如果 order 为 null
 */
public Money calculateTotal(Order order) {
  Objects.requireNonNull(order, "Order must not be null");
  // ...
}

// 改善前：大量注释
public class OrderProcessor {
  // 处理订单
  public void process(Order order) {
    // 验证订单
    if (order == null) throw new IllegalArgumentException();
    if (order.getItems().isEmpty()) throw new IllegalArgumentException();
    
    // 计算总价
    double total = 0;
    for (Item item : order.getItems()) {
      total += item.getPrice() * item.getQuantity(); // 价格 * 数量
    }
    
    // 如果有VIP折扣
    if (order.getCustomer().isVip()) {
      total *= 0.9; // 打9折
    }
    
    // 保存订单
    repository.save(order);
    
    // 发送确认邮件
    emailService.send(order.getCustomer().getEmail(), 
                      "Order Confirmation", 
                      "Total: $" + total);
  }
}

// 改善后：代码自解释
public class OrderProcessor {
  private final OrderRepository repository;
  private final EmailService emailService;
  
  public void process(Order order) {
    validateOrder(order);
    Money total = calculateTotal(order);
    repository.save(order);
    sendConfirmationEmail(order, total);
  }
  
  private void validateOrder(Order order) {
    if (order == null) {
      throw new IllegalArgumentException("Order must not be null");
    }
    if (order.getItems().isEmpty()) {
      throw new IllegalArgumentException("Order must have items");
    }
  }
  
  private Money calculateTotal(Order order) {
    Money subtotal = calculateSubtotal(order);
    if (order.getCustomer().isVip()) {
      return subtotal.multiply(VIP_DISCOUNT_RATE);
    }
    return subtotal;
  }
  
  private Money calculateSubtotal(Order order) {
    return order.getItems().stream()
        .map(item -> item.getPrice().multiply(item.getQuantity()))
        .reduce(Money.ZERO, Money::add);
  }
  
  private void sendConfirmationEmail(Order order, Money total) {
    emailService.send(
        order.getCustomer().getEmail(),
        "Order Confirmation",
        "Your order total: " + total
    );
  }
  
  private static final double VIP_DISCOUNT_RATE = 0.9;
}