26｜文档字符串与类型注解

这套课程按知识依赖排列。本篇的前置知识是：第 23 篇。学完后，你应该能够给函数写清输入、输出和用途。

本篇要解决的问题

本篇只处理“文档字符串与类型注解”这一件事。示例基于 Python 3.14.6，在 macOS 环境核验；除明确标注的终端命令外，代码本身只使用 Python 标准能力。

先看清一个容易误解的细节

类型注解为读者和工具描述预期类型，但 Python 默认不会仅凭注解阻止不同类型的实参进入函数。

核心概念

• 文档字符串紧跟在函数定义后的第一条语句。
• 注解表达接口意图，不代替输入校验和测试。
• 基础注解优先使用 str、int、list[str] 等直接写法。

跟着示例运行

把下面代码保存到本课脚本并运行：

def format_score(name: str, score: int) -> str:
    """返回带姓名的分数文本。"""
    return name + "：" + str(score)

print(format_score("小郑", 95))
print(format_score.__doc__)

预期结果：

小郑：95
返回带姓名的分数文本。

输出中包含环境路径、集合元素或日志格式时，具体文字和顺序可能随本机环境变化；判断是否成功应以本篇说明的关键结果为准。

按执行顺序拆开看

1. 函数签名说明 name 预期为字符串、score 预期为整数，返回值预期为字符串。
2. 运行时仍按函数体实际表达式执行；注解主要服务读者、编辑器和静态检查工具。

初学者容易混淆的地方

• 认为加了 score: int 后，Python 会自动拒绝字符串。默认运行时不会这样校验。
• 注解写得比接口本身更复杂，反而增加初学者负担；先准确表达基础容器和可选值。

练习

1. 为面积函数补充参数和返回值注解。
2. 通过 函数名.__doc__ 查看文档字符串。

练习应先独立完成，再通过增加 print 输出或检查文件内容观察中间状态。当前课程尚未讲到的能力，不要求提前搜索复杂写法。

本篇边界

本篇目标是给函数写清输入、输出和用途。没有展开的高级机制会放到后续课程；先确保能够解释示例中每一行代码，再进入下一篇。