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学习网公众号，带你了解更多关于的知识点！