代码规范、命名与可读性

第 15 章 · 软件工程

读代码的时间远多于写代码。 命名一团糟（tmp、data2、doStuff）、缩进混用、注释要么没有要么过期，别人（或半年后的自己）要花很久才能看懂「这段到底在干什么」。代码规范与可读性就是为了让代码好读、好改、好协作：本章讲命名规范（变量、函数、类、文件）、格式与风格（linter、formatter）、注释与自解释代码，以及团队规范与工具落地。

一、命名规范：变量、函数、类、文件

好名字是最好的一种注释：见名知意，减少猜和查。命名要一致、有意义、符合语言与团队约定。

变量 / 字段

名词或名词短语，表「是什么」：orderTotal、userName、isActive。布尔常用 is/has/can 前缀。循环里单字母 i、j 可接受，其他避免 x、data。

函数 / 方法

动词或动词短语，表「做什么」：calculateTotal()、getUserById()、saveOrder()。返回布尔可用 isValid()、hasPermission()。

类 / 类型

名词，表「是什么」：Order、UserService、PaymentGateway。避免泛称 Manager、Handler 堆砌，尽量体现职责。

文件 / 模块

与主类型或功能一致：order_service.py、UserRepository.ts。多词用下划线或短横线，与项目约定统一。

易读

const orderTotal = calculateOrderTotal(items, discount);
if (orderTotal > 0) {
  await saveOrder(orderTotal);
}

难读

const x = f(a, b);
if (x > 0) {
  g(x);
}

命名对比：见名知意 vs 无意义缩写

不同语言有不同习俗：如 Python 用 snake_case 做函数与变量、PascalCase 做类；JavaScript/TypeScript 常用 camelCase 做变量与函数、PascalCase 做类；常量可用 UPPER_SNAKE。团队内保持一致比「绝对正确」更重要。

二、格式与风格：Linter、Formatter

格式包括缩进、换行、括号位置、行宽等。人工统一容易漂移，用工具自动保证：Linter 检查潜在错误与风格违规（未用变量、命名风格、复杂度等）；Formatter 按规则自动排版（如 Prettier、Black、gofmt），保存即格式化。两者配合：Formatter 管「长什么样」，Linter 管「哪里有问题」。

Source Code → Linter → Formatter → Consistent Style

代码经 Linter 检查、Formatter 排版，得到一致风格

建议：在项目里加入 Linter 和 Formatter 配置（如 ESLint + Prettier、Ruff + Black），并在 CI 里跑 Lint，未通过则不允许合并。这样风格争议由工具解决，大家把精力放在逻辑与设计上。

三、注释与自解释代码

注释解释「为什么」和「在什么前提下」——复杂业务规则、非常规写法、坑与约束。不要用注释复述「这段在做什么」；若逻辑简单，应通过自解释代码（好命名、小函数、清晰结构）让读者直接看懂。注释会过期，代码一改注释忘改就会误导人，所以能靠命名和结构说清的就不写注释。

自解释 + 必要注释

// 折扣仅在活动期内、且订单满 100 时生效（业务约定 2024-01）
const effectiveDiscount = campaign.isActive() && orderTotal >= 100
  ? applyDiscount(orderTotal, campaign.rate)
  : 0;

注释复述代码

// 判断是否有效
const e = a && b >= 100 ? c(d, r) : 0;

注释说明「为什么/前提」；避免用注释复述代码

文档注释（如 JSDoc、docstring）对公共 API 很有用：参数、返回值、异常、示例。内部实现可少写，把「意图」放在函数名和分层里。

四、团队规范与工具落地

规范只有写进文档、配进工具、在 CI 里卡住才会真正落地。建议：

规范文档：命名约定、目录结构、注释要求、提交信息格式等，放在仓库里并随项目更新。
EditorConfig / Prettier / ESLint 等：统一缩进、引号、行尾、Lint 规则，新人 clone 即生效。
CI 检查：提交或 PR 时自动跑 Lint 和格式检查，不通过不给合并，避免「口头规范」被忽略。
Code Review 带上可读性：命名是否清晰、是否有无意义注释、复杂逻辑是否可拆，在 Review 里一并看。

一句话： 可读性靠命名（变量/函数/类/文件一致、见名知意）、格式（Linter + Formatter 自动统一）、注释（写「为什么」和前提，能自解释就不写）、团队规范与工具（文档 + 配置 + CI）落地，让读代码的时间省下来。

小贴士： 起名卡壳时，先想「这段在业务里叫什么」——业务里叫「订单实付金额」，代码里就叫 orderPaidAmount 或 paidAmount，比 result、val 好得多。

五、小结

命名：变量/字段用名词、函数用动词、类用名词，与语言和团队约定一致。格式与风格：用 Linter 查问题、Formatter 统一排版，并在 CI 中强制。注释：说明「为什么」和前提，避免复述代码；能自解释的用好命名和小函数代替。团队规范：写进文档、配进工具、CI 卡住、Review 关注可读性。下一章讲重构：何时重构与如何安全重构，把「怎么在不破坏功能的前提下改善结构」落到实处。