第4章 编码规范实践

4.1 命名规范

一致的命名是代码可读性的基石。团队应约定变量、函数、类、常量等标识符的命名风格，并借助工具强制检查。

4.2 代码注释规范

注释应解释“为什么”而非“是什么”。推荐使用 JSDoc / Docstring 风格，并遵循以下原则：

• 公共 API：必须包含用途、参数、返回值、异常。
• 复杂逻辑：用行注释说明算法意图。
• TODO / FIXME：附带责任人及跟踪链接。
• 避免：冗余注释、注释掉的代码块（应直接删除）。

/**
 * 计算订单折扣金额
 * @param {number} total - 订单原始总价
 * @param {string} couponCode - 优惠券代码
 * @returns {number} 折扣后金额
 * @throws {InvalidCouponError} 当优惠券无效时
 */
function applyDiscount(total, couponCode) {
  // 黑五期间额外叠加折扣 (临时逻辑)
  if (isBlackFriday) {
    return total * 0.7;
  }
  // ... 其余逻辑
}

4.3 代码格式化工具

自动化格式化消除风格争议，保证仓库一致性。主流工具对比：

推荐在项目中统一配置，并在 CI 阶段执行格式化检查。

4.4 代码审查清单

审查清单帮助 Reviewer 聚焦关键点，避免遗漏。以下为核心检查项：

• 命名与风格：是否符合团队规范？有无拼写错误？
• 注释质量：公共接口是否文档化？复杂逻辑是否解释？
• 代码重复：是否存在可抽取的公共逻辑？
• 错误处理：边界条件、异常路径是否覆盖？
• 安全性：输入校验、SQL注入、XSS 防范。
• 性能：不必要的循环、大对象分配、N+1 查询。