14.1 什么是注释？ #
注释是不会被执行的说明文字，用于解释意图、临时禁用代码。Python 解释器会忽略它们。
# 单行注释
print("Hello") # 行尾注释
# print("调试输出") # 临时禁用某行14.2 单行与多行 #
| 方式 | 写法 | 说明 |
|---|---|---|
| 单行 | # |
最常用 |
| 多行 | 每行加 # |
块说明、分段说明 |
| 文档字符串 | """...""" |
紧贴函数/类/模块，是字符串对象，可作说明用 |
# 配置区
# DATABASE_URL = "..."
# MAX_RETRY = 3
def greet(name):
"""向用户打招呼（模块/函数文档用 docstring）"""
return f"Hello, {name}"14.3 文档字符串（docstring） #
项目里给对外暴露的函数、类写 docstring，说明用途、参数和返回值，便于团队协作和 IDE 提示：
def create_user(name: str, age: int) -> dict:
"""
创建用户记录。
Args:
name: 用户名
age: 年龄
Returns:
包含 id、name、age 的字典
"""
return {"name": name, "age": age}团队可约定 Google / NumPy 等 docstring 风格，保持统一即可。
14.4 写法建议 #
解释「为什么」，不要重复「是什么」：
# 不好：x = x + 1 # 给 x 加 1
# 好：补偿 API 返回的页码从 1 开始，内部索引用 0 开始
page_index = page - 1常用标记（可选）：
# TODO: 接入真实支付接口
# FIXME: 并发下可能重复提交14.5 项目开发要点 #
- 代码优先于注释：变量、函数命名清晰，比大段注释更有价值
- 公共接口写 docstring：模块、类、对外函数；内部简单逻辑不必每行注释
- 提交前删掉调试注释：临时的
# print(...)、# breakpoint不要进仓库 - 注释与代码同步：逻辑改了却留着旧注释，比没注释更危险
- 避免废话注释：
# 初始化、# 开始循环这类可删 - 类型注解：
def foo(name: str) -> bool能替代部分参数说明（