一句话定义
软件文档说明功能如何使用、接口有哪些约束,以及设计为何如此。教程、操作指南、参考与解释各自服务不同阅读任务。
为什么重要
- 代码只能说明“怎么做”,说不清“为什么”:为什么选这个算法、为什么这个参数不能为 0,需要文档。
- 降低使用门槛:清楚的安装、配置与最小示例能降低首次使用的门槛。
- AI 编程助手会读文档:工具可能把 docstring、类型提示、README 或规则文件作为上下文,读取范围取决于具体工具。
使用边界
doctest 能检查被执行的示例,不能验证所有叙述。AGENTS.md 的读取规则取决于具体工具;llms.txt 是文档入口提案,不能假定所有模型或客户端都会读取。
原理 / 图解
Diátaxis 框架把技术文档分为四类,各自满足不同需求:https://diataxis.fr/
代码层面的文档层次:
| 层次 | 载体 | 写什么 |
|---|---|---|
| 行内 | 注释 # |
为什么这样写(非显而易见的原因) |
| 函数 / 类 | docstring | 做什么、参数、返回值、异常、示例 |
| 模块 / 包 | 模块 docstring、__init__.py |
这个模块负责什么 |
| 项目 | README、CHANGELOG、CONTRIBUTING | 怎么安装、怎么用、怎么贡献 |
| 系统 | 架构文档、ADR(架构决策记录) | 关键设计决策与取舍 |
Python 的 docstring 约定见 PEP 257:https://peps.python.org/pep-0257/ 。常见的 docstring 风格有 Google 风格、NumPy 风格和 reStructuredText 风格。
可运行示例
一个 Google 风格的 docstring,其中的示例同时是可执行的测试(doctest),并用 help() 查看(Python 3.15.0 一稿运行记录):
# 文件:examples/11_documentation.py
"""文档的三层:docstring(给调用者)、注释(解释"为什么")、doctest(可执行的示例)"""
def chunk(items: list, size: int) -> list[list]:
"""把列表按固定大小切块。
Args:
items: 待切分的列表。
size: 每块大小,必须为正整数。
Returns:
切分后的列表的列表;最后一块可能不足 size。
Raises:
ValueError: size <= 0 时。
Examples:
>>> chunk([1, 2, 3, 4, 5], 2)
[[1, 2], [3, 4], [5]]
>>> chunk([], 3)
[]
"""
if size <= 0:
raise ValueError("size 必须为正整数")
# 用切片而不是逐个 append:可读性更好,且对大列表更快(为什么,而不是做什么)
return [items[i:i + size] for i in range(0, len(items), size)]
if __name__ == "__main__":
import doctest
result = doctest.testmod(verbose=False)
print(f"doctest: 尝试 {result.attempted} 个示例,失败 {result.failed} 个")
help(chunk)
一稿留存输出:
doctest: 尝试 2 个示例,失败 0 个
Help on function chunk in module __main__:
chunk(items: list, size: int) -> list[list]
把列表按固定大小切块。
Args:
items: 待切分的列表。
size: 每块大小,必须为正整数。
Returns:
切分后的列表的列表;最后一块可能不足 size。
Raises:
ValueError: size <= 0 时。
Examples:
>>> chunk([1, 2, 3, 4, 5], 2)
[[1, 2], [3, 4], [5]]
>>> chunk([], 3)
[]
doctest 的价值:文档里的示例一旦和代码不一致,测试就会失败,有助于发现被执行示例中的过时内容。https://docs.python.org/3/library/doctest.html
常见误区
- 注释复述代码:
x = x + 1 # x 加 1毫无价值。注释应解释意图和原因。 - 只写 API 参考,不写教程:参数表很全,但新人不知道从哪开始——这正是 Diátaxis 要解决的问题。
- 文档与代码分离太远:放在别处的 Wiki 很快过时。“文档即代码(Docs as Code)”:文档和代码放在同一仓库、同一评审流程里。
- README 里写死版本号和截图却从不更新。
与 AI 开发的关系
- AI 规则文件是一种新型文档:如
AGENTS.md、各编辑器的项目规则文件,用来告诉编程助手项目约定、构建命令、禁止事项。AGENTS.md 约定的说明站点:https://agents.md/ - 让 AI 写文档效率很高,但必须核对:AI 容易编造不存在的参数或夸大功能。doctest 可以自动核对其中的示例。
- 文档质量是 RAG 效果的重要因素之一,检索与生成设置同样需要检查:企业知识库问答效果差,往往根子在原始文档本身结构混乱。
延伸阅读
- Diátaxis:https://diataxis.fr/
- PEP 257 – Docstring 约定:https://peps.python.org/pep-0257/
- Google Python 风格指南·注释与 docstring:https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings
- Sphinx 文档工具:https://www.sphinx-doc.org/;MkDocs:https://www.mkdocs.org/
理解检查
安装步骤成功,但配置示例引用不存在的参数,文档算验证通过吗?
参考答案:不算。需要分别检查安装流程、参数参考和示例是否与当前版本一致。
核验与复现
核验日期:2026-10-14。示例状态:运行通过。本轮日志:11_documentation.py。
配套代码与核验资料