Python注释规范与文档编写技巧

本篇文章主要是结合我之前面试的各种经历和实战开发中遇到的问题解决经验整理的，希望这篇《Python注释与文档规范详解》对你有很大帮助！欢迎收藏，分享给更多的需要的朋友学习~

Python注释只能用#，三引号字符串不是注释；docstring必须位于模块/函数/类定义正下方首行，用"""包裹并绑定__doc__属性；推荐Google或NumPy风格，需统一且聚焦“为什么”而非“做什么”。

Python注释和文档字符串（docstring）不是可有可无的装饰，而是代码可维护性、协作效率和工具集成的基础。写得清楚的注释能帮别人（包括未来的你）快速理解意图；规范的 docstring 则让 help()、IDE 提示、Sphinx 文档生成等真正可用。

单行注释与多行注释：用 #，别用 ''' 或 """ 模拟

Python 只有一种注释语法：# 后的内容到行尾均为注释。三引号括起来的字符串（'''...''' 或 """..."""）本质是字符串字面量，不是注释——即使没赋值给变量，它仍会被 Python 解析并占用内存（虽然通常被优化掉）。除非是 docstring，否则别用三引号“假装”写注释。

正确写法：

• # 计算用户等级，按积分区间划分
• x = x + 1 # 增量更新，避免重复查询数据库

错误写法（浪费资源且易误导）：

• """这是注释""" # 实际是未使用的字符串，不是注释
• '''调试用：暂时屏蔽这部分逻辑''' # 同样不是注释，可能意外触发 __doc__ 赋值

docstring 的位置与基本格式：模块开头、函数/类定义后立即跟上

docstring 必须出现在模块、函数、类或方法定义的**正下方第一行**，且必须使用三重双引号 """...（PEP 257 推荐，也更常见于工具链支持）。它会自动绑定到对象的 __doc__ 属性。

示例：

"""处理用户注册请求的工具模块。"""
def validate_email(email: str) -> bool:
"""检查邮箱格式是否符合基本规范。
Args:
    email: 待验证的邮箱字符串

Returns:
    True 表示格式有效，False 表示无效
"""
return "@" in email and "." in email.split("@")[-1]

注意：空行、缩进、额外空格都会影响解析。函数体第一行不能是空行，否则 docstring 会被视为普通字符串。

Google 风格 vs NumPy 风格：选一种，保持项目统一

没有强制标准，但团队内必须统一。主流是 Google 风格（简洁，适合 IDE 快速提示）和 NumPy/SciPy 风格（字段对齐清晰，适合生成 HTML 文档）。

Google 风格要点：

• 首行简明概括功能（句末不加句号）
• 空一行后写详细说明（可分段）
• 参数、返回值、异常等用 Args:、Returns:、Raises: 标记，每项缩进 4 空格，冒号后空一格

NumPy 风格要点：

• 首行仍是简述（句末不加句号）
• 空一行后，各字段名（如 Parameters、Returns）独占一行，下划线对齐（如 ----------），参数逐行列出，类型写在括号里
• 更强调结构化，适合复杂函数

无论哪种，都应避免冗余描述已有代码逻辑（如 # 将 x 加 1），而聚焦于“为什么这么做”“边界条件是什么”“调用者需注意什么”。

哪些地方必须写 docstring？哪些可以省略？

PEP 257 建议：所有公共模块、函数、类、方法都应有 docstring；私有成员（以下划线开头）可酌情省略；极简包装器或明显语义的属性可不写。

建议写的情况：

• 导出给其他模块调用的函数（尤其含参数/返回值逻辑）
• 类的 __init__ 方法（说明初始化行为和参数含义）
• 有副作用的操作（如写文件、发请求、修改全局状态）
• 算法关键步骤或业务规则封装（如 calculate_discount()）

可不写的情况：

• 纯数据容器类（如 namedtuple 或仅带属性的 dataclass）
• 重写父类方法但行为完全一致（此时继承父类 docstring 更合适）
• 测试函数（pytest 用函数名表达意图，必要时用注释说明特殊 case）

不复杂但容易忽略：写 docstring 不是为了应付检查，而是为了降低下次读这段代码时的认知负荷。

本篇关于《Python注释规范与文档编写技巧》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于文章的相关知识，请关注golang学习网公众号！