Python注释应说明“为什么”而非“做什么”，需清晰简洁、聚焦决策理由；函数文档字符串须结构化，标明参数类型、返回值及异常；行内注释宜简短右对齐；注释须随代码同步更新，避免过期误导。
Python注释不是写给机器看的，而是写给人看的——尤其是未来的你或团队里的其他人。写得清楚、简洁、有重点的注释，能让别人（和你自己）快速理解代码意图，而不是猜逻辑。
注释要说明“为什么”，而不是“做什么”
代码本身已经表达了“做什么”，重复描述只会增加噪音。真正需要解释的是决策背后的理由：为什么用这个算法？为什么这里要绕过某个异常？为什么参数设为这个值？
- ❌ 差的写法：# 计算x的平方
x = x ** 2 - ✅ 好的写法：# 使用**2而非pow(x,2)，因性能更高且避免类型转换开销
x = x ** 2 - ✅ 另一个例子：# 这里不校验None，因上游已确保data非空（见utils.validate_input）
process(data)
函数文档字符串（docstring）要结构化
用三重引号写的函数级注释，建议遵循Google或NumPy风格，明确写出参数、返回值、异常和用途。IDE和工具（如Sphinx）能自动提取这些信息。
- 写清每个参数的类型和含义，特别是布尔或魔法值（如
inplace=True） - 标明返回值是否可能为
None，或在什么条件下返回不同类型 - 简短说明函数职责，一句话概括，别写成操作步骤列表
示例：
立即学习“Python免费学习笔记（深入）”；
"""计算用户活跃度得分，基于最近7天登录频次与操作时长加权。Args:
user_id (int): 用户唯一标识
include_bonus (bool): 是否叠加节日奖励分，默认False
Returns:
float: 活跃度得分，范围0.0–100.0；若用户无历史数据则返回0.0
Raises:
ValueError: 当user_id为负数时抛出"""
行内注释慎用，保持右对齐且不过长
行内注释（写在代码同行右侧）只用于极简说明，且必须与代码保持至少两个空格，建议统一右对齐（多数编辑器支持自动对齐插件）。超过一行或含复杂逻辑的说明，请改用上行注释。
- ✅ 推荐：
timeout = 30 # 单位：秒，避免阻塞API网关 - ❌ 避免：
timeout = 30 # 这个超时时间是根据Nginx默认keepalive_timeout设的，不能大于它否则会断连 - ⚠️ 注意：不要在每行赋值后都加注释，比如
a = 1 # a是1——这是冗余的
及时更新注释，过期注释比没有更危险
代码重构后，最容易被忽略的就是注释。一句错误的注释可能误导排查方向，浪费数小时。把注释当作代码的一部分来维护：
- 修改逻辑前，先扫一眼相关注释，判断是否还需保留或重写
- Code Review时，把注释准确性列为检查项之一
- CI流程中可加入简单检查（如用
pylint --enable=invalid-docstring识别明显缺失或格式错误的docstring）
