Python注释只能用#，三引号字符串不是注释；docstring必须位于模块/函数/类定义正下方首行，用"""包裹并绑定__doc__属性；推荐Google或NumPy风格，需统一且聚焦“为什么”而非“做什么”。
Python注释和文档字符串（docstring）不是可有可无的装饰，而是代码可维护性、协作效率和工具集成的基础。写得清楚的注释能帮别人（包括未来的你）快速理解意图；规范的 docstring 则让 help()、IDE 提示、Sphinx 文档生成等真正可用。
单行注释与多行注释：用 #，别用 ''' 或 """ 模拟
Python 只有一种注释语法：# 后的内容到行尾均为注释。三引号括起来的字符串（'''...''' 或 """..."""）本质是字符串字面量，不是注释——即使没赋值给变量，它仍会被 Python 解析并占用内存（虽然通常被优化掉）。除非是 docstring，否则别用三引号“假装”写注释。
正确写法：
# 计算用户等级，按积分区间划分x = x + 1 # 增量更新，避免重复查询数据库
错误写法（浪费资源且易误导）：
立即学习“Python免费学习笔记（深入）”；
"""这是注释""" # 实际是未使用的字符串，不是注释'''调试用：暂时屏蔽这部分逻辑''' # 同样不是注释，可能意外触发 __doc__ 赋值
docstring 的位置与基本格式：模块开头、函数/类定义后立即跟上
docstring 必须出现在模块、函数、类或方法定义的**正下方第一行**，且必须使用三重双引号 """...（PEP 257 推荐，也更常见于工具链支持）。它会自动绑定到对象的 __doc__ 属性。
示例：
"""处理用户注册请求的工具模块。"""
<p>def validate_email(email: str) -> bool:
"""检查邮箱格式是否符合基本规范。</p><pre class="brush:php;toolbar:false;">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 不是为了应付检查，而是为了降低下次读这段代码时的认知负荷。
