1. 什么是注释？ #

• 注释是不会被执行的说明文字，用于解释意图、临时禁用代码。
• Python 解释器会忽略它们。

# 单行注释
print("Hello")  # 行尾注释

# print("调试输出")  # 临时禁用某行

2. 单行与多行 #

# 配置区
# DATABASE_URL = "..."
# MAX_RETRY = 3

def greet(name):
    """向用户打招呼（模块/函数文档用 docstring）"""
    return f"Hello, {name}"

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 风格，保持统一即可。

4. 写法建议 #

• 解释「为什么」，不要重复「是什么」：

# 不好：x = x + 1  # 给 x 加 1

# 好：补偿 API 返回的页码从 1 开始，内部索引用 0 开始
page_index = page - 1

• 常用标记（可选）：

# TODO: 接入真实支付接口
# FIXME: 并发下可能重复提交

5. 项目开发要点 #

• 代码优先于注释：变量、函数命名清晰，比大段注释更有价值。
• 公共接口写 docstring：模块、类、对外函数；内部简单逻辑不必每行注释。
• 提交前删掉调试注释：临时的 # print(...)、# breakpoint 不要进仓库。
• 注释与代码同步：逻辑改了却留着旧注释，比没注释更危险。
• 避免废话注释：# 初始化、# 开始循环 这类可删。
• 类型注解：def foo(name: str) -> bool 能替代部分参数说明。