PEP 257 是什么
PEP 257 是 Python 文档字符串（docstring）的约定：用三重双引号包裹，首行是一句摘要，空行之后写细节，摘要行惯用祈使句描述行为。docstring 会被 help()、Sphinx 以及各类 IDE 提示直接读取，所以它既是给人看的说明，也是工具链的输入。
基本信息
| 形态 | 首行摘要，空行之后是详细说明 |
|---|---|
| 引号 | 三重双引号，与代码缩进对齐 |
| 消费方 | help()、Sphinx、IDE 提示、文档生成工具 |
| 常见检查 | pydocstyle，或 Ruff 的 D 系列规则 |
典型使用场景
- 公共库与 SDK：docstring 直接决定使用者能否快速上手
- 内部模块：解释参数含义与异常约定，减少口头问答
- 生成 API 文档：docstring 是文档站点的内容来源
- 类型注解之外补充语义：说明单位、取值范围与副作用
- 遗留模块梳理：先给关键函数补摘要，再逐步补细节
摘要行与细节的分工
- 摘要行：一句话说清做什么，用祈使句
- 细节段：参数含义、返回值、会抛出的异常
- 实现细节：放在普通注释里，不写进 docstring
- 过时描述：改代码时同步更新，宁缺毋错
示例
示例
def add(a, b):
"""返回 a 与 b 之和。"""
return a + b
def transfer(src, dst, amount):
"""从 src 账户向 dst 账户转账。
金额单位为分；余额不足时抛出 ValueError。
"""常见问题
| 问题 | 影响 |
|---|---|
| 摘要行与细节之间缺空行 | 部分工具解析出错误的摘要 |
| docstring 与签名不同步 | 参数改名后描述仍在讲旧参数 |
| 把实现细节写进 docstring | 使用者看到大量内部约定 |
| 引号风格混用 | 格式检查与自动修复反复改动 |
docstring 描述的是对外行为：调用者需要知道的单位、取值范围与异常，比内部实现细节更值得写进去。
摘要行用祈使句（返回、计算、合并）比第三人称叙述更符合惯例，也更容易被工具正确截取。