文档(Documentation)

软件文档说明功能如何使用、接口有哪些约束,以及设计为何如此。教程、操作指南、参考与解释各自服务不同阅读任务。

一句话定义

软件文档说明功能如何使用、接口有哪些约束,以及设计为何如此。教程、操作指南、参考与解释各自服务不同阅读任务。

为什么重要

  • 代码只能说明“怎么做”,说不清“为什么”:为什么选这个算法、为什么这个参数不能为 0,需要文档。
  • 降低使用门槛:清楚的安装、配置与最小示例能降低首次使用的门槛。
  • AI 编程助手会读文档:工具可能把 docstring、类型提示、README 或规则文件作为上下文,读取范围取决于具体工具。

使用边界

doctest 能检查被执行的示例,不能验证所有叙述。AGENTS.md 的读取规则取决于具体工具;llms.txt 是文档入口提案,不能假定所有模型或客户端都会读取。

原理 / 图解

Diátaxis 框架把技术文档分为四类,各自满足不同需求:https://diataxis.fr/

图 1

代码层面的文档层次:

层次 载体 写什么
行内 注释 # 为什么这样写(非显而易见的原因)
函数 / 类 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 效果的重要因素之一,检索与生成设置同样需要检查:企业知识库问答效果差,往往根子在原始文档本身结构混乱。

延伸阅读

理解检查

安装步骤成功,但配置示例引用不存在的参数,文档算验证通过吗?

参考答案:不算。需要分别检查安装流程、参数参考和示例是否与当前版本一致。

核验与复现

核验日期:2026-10-14。示例状态:运行通过。本轮日志:11_documentation.py。

配套代码与核验资料

继续浏览基础 返回知识 →返回顶部 ↑
本篇目录
教程图解100%
教程图解