第4章 选择好名字与设计API

为什么好名字重要

想象一条工厂流水线，每个工位都贴着标签，告诉你手里这个零件是什么、要往哪送、送错了会怎样。代码里的名字就是这些标签。一个叫 data 的箱子，你知道里面有东西，却不知道是什么、单位是几个，只能拆开看。

没有好名字，读者每碰上一段代码都得钻进去搞清楚它要什么、给出什么、什么时候会出错。一个团队写了几个月，新人接手时面对满屏 info、manager、tmp，光理清谁调谁就要好几天，改一处还怕牵连一片。

好名字加上清楚的参数写法，就是让代码自己说话：名字告诉你这是什么、单位是多少，写法告诉你什么必传、什么可选、拼错了立刻报错。这样别人不用读你的实现，也能放心地用。

原书骨架与现代迁移

官方章节围绕PEP 8与命名风格、参数设计、名称指南、命名空间与API、弃用与质量工具展开。原书出版于Python 2.5与早期敏捷工具生态，本章保留它解释"为什么"的结构；命令和安全默认按当前Python、标准库与PyPA维护文档迁移，不把EasyInstall、distutils安装命令、旧CI或旧项目平台直接当成新项目默认。

承接前两项，把局部语法或工具放回应用数据流。阅读时沿输入、协议、状态、输出和证据追踪，避免只背API名称。

把关键字参数边界用代码固化下来：必需项用 位置参数 承担，可选项用 关键字限定参数 隔离，下面两种写法对比同一个"加载记录"接口：

def load_records(path, *, encoding="utf-8", strict=True):
    """Load records from path with explicit policy controls."""
    ...

path     位置必传 —— 每次调用都要给，不能遗漏
encoding 关键字可选 —— 调用方写全名，拼错即报错
strict   关键字开关 —— 默认严格，宽松模式需显式声明

下面用交互台把参数边界摆出来：先预测把可选项改成只能按名字传、拼错名字会怎样，再动手验证；打开"注入故障"还能看接口怎么失败。

机制一：责任与数据流

名字应按变量、常量、函数、类和模块的角色保持一致；风格检查能发现形式偏差，但语义是否准确仍需领域评审。 参数从真实用例迭代出来，必需项、默认值和关键字边界共同形成API；任意参数能扩展接口，也可能吞掉拼写错误和破坏可发现性。 先写出公共行为和失败类型，再选择语法或工具。这样即使实现从原书工具迁到当前生态，调用者仍能依据相同契约判断结果。

提醒我们：抽象不能消除成本，只会改变成本出现的位置。包装、生成器、构建系统、CI或缓存都必须说明资源、顺序和异常传播。

弃用旧 API 时，替代路径要和 弃用告警 同时给出，下面两种视角对比同一段迁移逻辑：

import warnings
 
def old_api(value):
    warnings.warn("use new_api", DeprecationWarning, stacklevel=2)
    return new_api(value)

替代路径  指向 new_api，调用方能立即迁移
告警类型  DeprecationWarning，工具链可捕获
调用深度  stacklevel=2，告警指向调用方而非本函数
删除期限  需在文档标明主版本号，到期才删除

机制二：失败与边界

布尔名称表达判断，序列用复数，映射说明键值含义，并避免data、manager等泛称；名称应让读者无需展开实现即可预测单位和失败。 模块树决定用户导入路径，公共API要小而稳定；内部重排通过 显式导出 隔离，不能把所有实现细节暴露为偶然契约。 边界实验至少包含正常、空输入、上限附近、依赖失败和重复执行。涉及网络、并发或外部制品时，再加入超时、取消、部分完成与摘要校验。

历史工具不等于无价值。正确迁移是先提取声明式配置、隔离、持续反馈和可回滚发布等不变量，再用维护中的接口重写；错误做法是机械替换命令却保留隐式环境和不可追踪副作用。

公共 API 要小而稳定，__all__ 把内部重排隔离起来，下面两种视角对比同一段导出逻辑：

__all__ = ["Client", "connect"]
 
from .client import Client
from .transport import connect

__all__  白名单 —— 只有这些名字对 from package import * 可见
Client   类导出 —— 内部拆分不影响外部导入路径
connect  函数导出 —— 实现可从 transport 模块迁移，签名不变即可

机制三：证据闭环

负责收束验收。弃用要给替代路径、告警、期限和兼容窗口，再在主版本删除；静态检查与重复检测提供线索，最终变更仍需测试真实调用者。 保存解释器、依赖锁定、输入、命令、退出状态、关键输出和制品摘要，才能让另一台干净机器重放同一结论。

实战验收清单

1. 在隔离环境运行三段示例，记录解释器实现、版本和依赖来源。
2. 为核心行为增加正常、空输入、失败和重复执行测试，先看到失败再修改实现。
3. 清理缓存和临时文件后重跑，证明结果不依赖工作区残留。
4. 对历史命令写出当前替代路径，并说明保留的架构不变量与不再采用的安全默认。

迁移决策题

设想团队正在维护一个已经运行多年的Python服务：它仍依赖本章对应的历史工具，但业务不能停机。先不要直接重写。第一步列出PEP 8与命名风格承担的真实输入和输出，再用参数设计识别构建或运行时依赖；第二步把名称指南放进隔离实验，证明当前行为与失败类型；第三步用命名空间与API设计兼容层，让旧入口和新入口在同一组契约测试下运行；最后以弃用与质量工具保存制品摘要、性能或行为差异与回滚条件。只有新路径在正常、边界和故障输入上都达到既定条件，才逐步切换流量或调用者。这样迁移的是可验证契约，而不是把一个旧命令盲目替换为一个新命令。

常见误区

误区 1

现象 → 用 data、manager、info 等泛称命名 原因 → 读者无法从名字预测单位和失败，必须展开实现才能理解 修法 → 名字含领域语义：user_count 而非 data，retry_queue 而非 manager

误区 2

现象 → 用 **kwargs 吞掉所有可选参数 原因 → 拼写错误不报错，IDE 无法提示，API 不可发现 修法 → 必需项位置参数，可选项关键字参数，* 分隔符阻止位置穿透

误区 3

现象 → 弃用 API 只加注释不告警 原因 → 调用方看不到提示，升级后突然报错 修法 → 用 warnings.warn 加 DeprecationWarning + stacklevel=2，标明删除版本

误区 4

现象 → 模块里所有函数都暴露为公共 API 原因 → 内部重排会破坏外部导入路径，改动牵连面过大 修法 → 用 __all__ 白名单隔离内部实现，只暴露稳定接口

本章回顾

本章逐项覆盖PEP 8与命名风格、参数设计、名称指南、命名空间与API、弃用与质量工具。方法是用可读接口表达责任，用边界测试证明失败语义，再以可重建环境和制品证据完成闭环。

小结

• 命名按角色一致：布尔用判断词、序列用复数、映射说明键值含义
• 参数边界：必需项位置、可选项关键字，* 分隔防位置穿透
• 公共 API 要小而稳定，用 __all__ 隔离内部重排
• 弃用须给替代路径、告警、期限和兼容窗口
• 风格检查发现形式偏差，语义准确仍需领域评审

练习与验收

名词解释