| 形态 | 首行摘要 + 空行 + 详细说明 |
|---|---|
| 工具链 | 被 help()、Sphinx、IDE 提示读取 |
示例
示例
def add(a, b):
"""返回 a 与 b 之和。"""
return a + b
def transfer(src, dst, amount):
"""从 src 账户向 dst 账户转账。
金额单位为分；余额不足时抛出 ValueError。
"""摘要行用祈使句描述行为；实现细节放普通注释，不要写进 docstring。
PEP 257：docstring 规范
Python 文档字符串约定：三重双引号；首行摘要句 + 空行 + 细节段落；描述行为与参数含义，供帮助系统与 IDE 引用。
易错点
- docstring 与签名不同步：参数改名了文档没改
- 摘要行与细节之间缺空行：部分工具解析出错误摘要
数据来源与参考
- PEP 257 - Docstring Conventions（python.org）