Python单行多行注释与docstring规范写法

脚本专家

Python 代码注释不是解释器执行逻辑的一部分，但它直接影响可读性、IDE 提示、代码审查和 API 文档生成。下面围绕 Python 的单行注释、多行三引号、docstring，以及函数、类、模块、代码块、行内注释的写法，整理一套可落地的规范。

一、三种基础注释形式

1. 单行注释 #
单行注释以 # 开头，其后的内容被 Python 解释器忽略。常见用途是解释代码功能、调试时临时屏蔽代码、标记 TODO。规范建议 # 后加一个空格，再写注释内容。

2. # 计算圆的面积（单行注释在代码上方）
3. radius = 5
4. area = 3.14 * radius ** 2  # 单行注释在代码右侧
5. # 调试时临时禁用代码
6. # print('这行不会执行')

复制代码

不要写废话注释，例如 # 赋值给变量。代码本身能表达清楚时，少加注释。

2. 多行注释（三引号）
Python 没有专门的多行注释语法。三引号（三个单引号或三个双引号）创建的是多行字符串，通常被当作多行注释使用。未赋值给变量时，解释器会忽略它。

2. '''
3. 这是一个多行注释的示例
4. 可以跨越多行
5. 不会被Python执行
6. '''
7. def example_function():
8.     '''这是函数的文档字符串(docstring)
9.     用于说明函数的功能和用法
10.     '''
11.     pass
13. '''
14. 也可以使用三个单引号
15. 作为多行注释
16. '''

复制代码

注意：三引号本质是字符串，不是真正的注释语法；函数、类或模块定义后的第一个三引号字符串会成为 docstring。

3. 文档字符串 Docstring
Docstring 通常位于模块、函数、类或方法开头，用三引号包裹，用于解释功能、参数、返回值、异常等信息。它可以通过 __doc__ 访问，也能被 help()、pydoc、Sphinx 等工具解析。

2. def add(a, b):
3.     '''Return the sum of two numbers.
5.     Args:
6.         a (int): First number.
7.         b (int): Second number.
9.     Returns:
10.         int: Sum of a and b.
11.     '''
12.     return a + b
14. print(add.__doc__)
15. help(add)

复制代码

输出中会显示该 docstring 内容。多行 docstring 常见格式是：第一行简短描述，空一行，再写详细说明；缩进必须与代码块一致。

二、按代码结构写注释

函数/方法注释
函数或方法的 docstring 应说明功能、参数、返回值，必要时说明异常。它适合帮助其他开发者理解调用方式，也方便 Sphinx、pydoc 生成 API 文档，IDE 如 PyCharm、VSCode 也会显示提示。格式建议统一遵循 PEP 257，或采用 Google、NumPy 等风格。简单函数不必写得很长，但参数和返回值不要漏。

2. def calculate_area(length, width):
3.     '''
4.     计算矩形的面积。
6.     Args:
7.         length (float): 矩形的长度。
8.         width (float): 矩形的宽度。
10.     Returns:
11.         float: 矩形的面积（length * width）。
13.     Raises:
14.         ValueError: 如果length或width为负数。
15.     '''
16.     if length < 0 or width < 0:
17.         raise ValueError('长度和宽度必须为正数')
18.     return length * width

复制代码

类注释
类 docstring 用于解释类功能、属性和重要方法，位于类定义之后、方法定义之前。不要只写“这是一个 XX 类”。多行时第一行写简短摘要，再展开说明。

2. class Rectangle:
3.     '''表示二维矩形的类。
5.     该类提供了计算面积和周长的方法，
6.     并支持比较两个矩形的大小。
8.     Attributes:
9.         width (float): 矩形的宽度
10.         height (float): 矩形的高度
11.     '''
12.     def __init__(self, width, height):
13.         self.width = width
14.         self.height = height
16.     def area(self):
17.         '''计算并返回矩形的面积。'''
18.         return self.width * self.height

复制代码

模块注释
模块注释通常放在文件开头、import 之前，用三引号包裹，描述模块功能、作者、版本等信息。它可以通过 help() 或 __doc__ 查看，文档工具也会读取。

2. '''
3. 这是一个计算器模块
4. 提供基本的加减乘除运算功能，支持整数和浮点数计算。
5. 作者: Python学习者
6. 版本: 1.0.0
7. 最后更新: 2023-10-01
8. '''
9. def add(a, b):
10.     '''返回两个数的和'''
11.     return a + b

复制代码

代码块注释
代码块注释用于解释一段连续逻辑，例如复杂算法、业务分支。可以先用三引号写整体说明，也可以使用 # 加分隔线形成块状注释。重点是与代码同步更新，不要为显而易见代码加冗余说明。

2. '''
3. 这是一个计算斐波那契数列的函数
4. 参数：
5.     n: 要生成的数列项数
6. 返回值：
7.     包含n个斐波那契数的列表
8. '''
9. def fibonacci(n):
10.     a, b = 0, 1
11.     result = []
12.     for _ in range(n):
13.         result.append(a)
14.         a, b = b, a + b
15.     return result
17. # ======================================
18. # 这段代码处理用户登录验证流程：
19. # 1. 检查用户名是否存在
20. # 2. 验证密码是否匹配
21. # 3. 记录登录日志
22. # ======================================
23. if user_exists(username):
24.     if check_password(username, password):
25.         log_login_attempt(username, True)
26.         return True
27.     else:
28.         log_login_attempt(username, False)
29.         return False

复制代码

行内注释
行内注释写在代码行末尾或中间，用于快速说明意图。Python 中行内注释前应至少保留两个空格，注释内容要简洁。不要用行内注释解释显而易见的代码。

2. x = 5  # 初始化计数器
3. y = x * 2  # 计算双倍值
4. # 不推荐：
5. z = x + y  # 把x和y相加

复制代码

三、文档字符串常见风格

Google 风格
Google 风格在参数、返回值、异常等部分使用清晰的分节标题，适合团队协作和代码审查。它与 PEP 8 有细节差异，例如行长度约定可能不同；团队应明确采用哪一套规范，并可用 yapf 等工具辅助格式化。

2. def calculate_sum(a, b):
3.     '''计算两个数的和。
5.     Args:
6.         a (int): 第一个加数。
7.         b (int): 第二个加数。
9.     Returns:
10.         int: 两个数的和。
11.     '''
12.     return a + b

复制代码

关键点是：三重引号、参数类型、返回值说明、函数名 snake_case、4 空格缩进。

NumPy 风格
NumPy 风格常见于科学计算、机器学习、数据分析等场景，强调向量化操作、广播机制、布尔索引和视图，避免 Python 原生循环。写相关代码注释时，应特别说明数组维度、数据类型和内存拷贝问题。

2. import numpy as np
4. arr = np.array([1, 2, 3, 4, 5])
5. squares = arr ** 2
7. matrix = np.array([[1, 2, 3], [4, 5, 6]])
8. result = matrix * np.array([10, 100, 1000])
10. even_elements = arr[arr % 2 == 0]
11. sum_total = np.sum(arr)
12. view = arr[1:4]

复制代码

需要注意的是：向量化通常比显式循环更高效；广播规则不熟容易导致维度不匹配；大数组操作要关注内存；视图与副本行为不同；dtype 选择会影响内存和速度。

reStructuredText 风格
reStructuredText 是 Sphinx 等 Python 文档工具链常用的轻量标记语言。它适合编写项目文档、API 文档，并可转换为 HTML、LaTeX 等格式。使用时注意缩进一致、空行分隔结构、标题下划线长度不小于标题文本长度，特殊符号需要转义时用反斜杠。

2. 主标题
3. ======
5. 二级标题
6. --------
8. * 项目符号列表
9. * 第二个项目
11. 1. 数字列表
12. 2. 第二项
14. 代码块::
16.     def example():
17.         print('使用4空格缩进')
19. .. note::
20.     这是一个提示框
22. `超链接 <https://python.org>`_

复制代码

表格可以用 RST 表格语法；跨文档链接可用 :doc:`other_page` 或 :ref:`section-label`。

Epytext 风格
Epytext 是 Epydoc 工具默认支持的 docstring 标记格式，使用 @、L{} 等符号标注参数、返回值、异常等元素。标记符号应紧跟在行首或前导空格后，类型说明可选。它与 reStructuredText 的一个明显区别是使用 @ 而不是 : 作为标记前缀。

2. def calculate_area(width, height):
3.     '''
4.     Calculate the area of a rectangle.
5.     @param width: The width of the rectangle (in meters)
6.     @type width: float
7.     @param height: The height of the rectangle (in meters)
8.     @type height: float
9.     @return: The calculated area
10.     @rtype: float
11.     @raise ValueError: If either dimension is negative
12.     '''
13.     if width < 0 or height < 0:
14.         raise ValueError('Dimensions cannot be negative')
15.     return width * height

复制代码

总结
Python 注释规范的核心不是写得多，而是写得准。单行注释用 #，多行说明可用三引号但要知道它本质是字符串；函数、类、模块优先写 docstring，并能被 help()、__doc__、Sphinx 等工具读取。内容上要避免废话、过度注释和注释与代码不同步。风格上可遵循 PEP 257，并在 Google、NumPy、reStructuredText、Epytext 等常用格式中选择团队统一方案。