Python 代码注释规范指南

本规范基于 PEP 8 和 PEP 257，旨在提升代码的可读性、可维护性和团队协作效率。

注释类型一览

类型 用途
行内注释 解释某一行代码的目的或细节
块注释 注释一段逻辑相关的代码
文档字符串 Docstring 说明模块、函数、类、方法的用途与参数

行内注释规范

  • 用 # 开头，后跟 1 个空格
  • 避免写废话或重复内容
  • 置于代码 同一行 或 上一行
1
x = x + 1  # 增加偏移量，防止重复计算

块注释规范

  • 用于解释一段代码的作用或算法思想
  • 置于代码 上方
  • 每行以 # 开头，段内不空行
1
2
3
4
# 检查用户是否登录且拥有管理员权限
# 否则重定向到登录页面
if not user.is_admin:
    redirect_to_login()

文档字符串规范

  • 使用三重引号 """..."""，可单行也可多行
  • 应该出现在：
    • 模块开头
    • 函数 / 方法定义下方
    • 类定义下方
  • 建议包含：功能说明、参数（可选）、返回值（可选）

函数注释示例：

1
2
3
4
5
6
7
8
9
10
11
12
def add(a, b):
    """
    返回两个数的和。

    参数:
        a (int): 第一个加数
        b (int): 第二个加数

    返回:
        int: 两数之和
    """
    return a + b

命名建议（补充）

虽然不是注释，但命名与注释是可读性的核心：

  • 使用有意义的名字（如 user_count 而非 uc）
  • 函数名、变量名用小写加下划线（snake_case）
  • 类名用大写字母开头的驼峰式（CamelCase）

注释反例

1
2
3
x = 1  # 给 x 赋值为 1（重复代码）
# 增加1
x = x + 1  # 没说清“为什么”要加1

注释风格 Tips

  • 注释说明“为什么”写这段代码，而非“这段代码在做什么”
  • 避免中文拼音，统一使用中文或英文
  • 中文注释推荐写在代码 上方
  • 注释保持最新，与代码同步修改！