Python单行多行注释与docstring规范写法
Python 代码注释不是解释器执行逻辑的一部分，但它直接影响可读性、IDE 提示、代码审查和 API 文档生成。下面围绕 Python 的单行注释、多行三引号、docstring，以及函数、类、模块、代码块、行内注释的写法，整理一套可落地的规范。一、三种基础注释形式
1. 单行注释 #
单行注释以 # 开头，其后的内容被 Python 解释器忽略。常见用途是解释代码功能、调试时临时屏蔽代码、标记 TODO。规范建议 # 后加一个空格，再写注释内容。
# 计算圆的面积（单行注释在代码上方）
radius = 5
area = 3.14 * radius ** 2# 单行注释在代码右侧
# 调试时临时禁用代码
# print('这行不会执行')
不要写废话注释，例如 # 赋值给变量。代码本身能表达清楚时，少加注释。
2. 多行注释（三引号）
Python 没有专门的多行注释语法。三引号（三个单引号或三个双引号）创建的是多行字符串，通常被当作多行注释使用。未赋值给变量时，解释器会忽略它。
'''
这是一个多行注释的示例
可以跨越多行
不会被Python执行
'''
def example_function():
'''这是函数的文档字符串(docstring)
用于说明函数的功能和用法
'''
pass
'''
也可以使用三个单引号
作为多行注释
'''
注意：三引号本质是字符串，不是真正的注释语法；函数、类或模块定义后的第一个三引号字符串会成为 docstring。
3. 文档字符串 Docstring
Docstring 通常位于模块、函数、类或方法开头，用三引号包裹，用于解释功能、参数、返回值、异常等信息。它可以通过 __doc__ 访问，也能被 help()、pydoc、Sphinx 等工具解析。
def add(a, b):
'''Return the sum of two numbers.
Args:
a (int): First number.
b (int): Second number.
Returns:
int: Sum of a and b.
'''
return a + b
print(add.__doc__)
help(add)
输出中会显示该 docstring 内容。多行 docstring 常见格式是：第一行简短描述，空一行，再写详细说明；缩进必须与代码块一致。
二、按代码结构写注释
函数/方法注释
函数或方法的 docstring 应说明功能、参数、返回值，必要时说明异常。它适合帮助其他开发者理解调用方式，也方便 Sphinx、pydoc 生成 API 文档，IDE 如 PyCharm、VSCode 也会显示提示。格式建议统一遵循 PEP 257，或采用 Google、NumPy 等风格。简单函数不必写得很长，但参数和返回值不要漏。
def calculate_area(length, width):
'''
计算矩形的面积。
Args:
length (float): 矩形的长度。
width (float): 矩形的宽度。
Returns:
float: 矩形的面积（length * width）。
Raises:
ValueError: 如果length或width为负数。
'''
if length < 0 or width < 0:
raise ValueError('长度和宽度必须为正数')
return length * width
类注释
类 docstring 用于解释类功能、属性和重要方法，位于类定义之后、方法定义之前。不要只写“这是一个 XX 类”。多行时第一行写简短摘要，再展开说明。
class Rectangle:
'''表示二维矩形的类。
该类提供了计算面积和周长的方法，
并支持比较两个矩形的大小。
Attributes:
width (float): 矩形的宽度
height (float): 矩形的高度
'''
def __init__(self, width, height):
self.width = width
self.height = height
def area(self):
'''计算并返回矩形的面积。'''
return self.width * self.height
模块注释
模块注释通常放在文件开头、import 之前，用三引号包裹，描述模块功能、作者、版本等信息。它可以通过 help() 或 __doc__ 查看，文档工具也会读取。
'''
这是一个计算器模块
提供基本的加减乘除运算功能，支持整数和浮点数计算。
作者: Python学习者
版本: 1.0.0
最后更新: 2023-10-01
'''
def add(a, b):
'''返回两个数的和'''
return a + b
代码块注释
代码块注释用于解释一段连续逻辑，例如复杂算法、业务分支。可以先用三引号写整体说明，也可以使用 # 加分隔线形成块状注释。重点是与代码同步更新，不要为显而易见代码加冗余说明。
'''
这是一个计算斐波那契数列的函数
参数：
n: 要生成的数列项数
返回值：
包含n个斐波那契数的列表
'''
def fibonacci(n):
a, b = 0, 1
result = []
for _ in range(n):
result.append(a)
a, b = b, a + b
return result
# ======================================
# 这段代码处理用户登录验证流程：
# 1. 检查用户名是否存在
# 2. 验证密码是否匹配
# 3. 记录登录日志
# ======================================
if user_exists(username):
if check_password(username, password):
log_login_attempt(username, True)
return True
else:
log_login_attempt(username, False)
return False
行内注释
行内注释写在代码行末尾或中间，用于快速说明意图。Python 中行内注释前应至少保留两个空格，注释内容要简洁。不要用行内注释解释显而易见的代码。
x = 5# 初始化计数器
y = x * 2# 计算双倍值
# 不推荐：
z = x + y# 把x和y相加
三、文档字符串常见风格
Google 风格
Google 风格在参数、返回值、异常等部分使用清晰的分节标题，适合团队协作和代码审查。它与 PEP 8 有细节差异，例如行长度约定可能不同；团队应明确采用哪一套规范，并可用 yapf 等工具辅助格式化。
def calculate_sum(a, b):
'''计算两个数的和。
Args:
a (int): 第一个加数。
b (int): 第二个加数。
Returns:
int: 两个数的和。
'''
return a + b
关键点是：三重引号、参数类型、返回值说明、函数名 snake_case、4 空格缩进。
NumPy 风格
NumPy 风格常见于科学计算、机器学习、数据分析等场景，强调向量化操作、广播机制、布尔索引和视图，避免 Python 原生循环。写相关代码注释时，应特别说明数组维度、数据类型和内存拷贝问题。
import numpy as np
arr = np.array()
squares = arr ** 2
matrix = np.array([, ])
result = matrix * np.array()
even_elements = arr
sum_total = np.sum(arr)
view = arr
需要注意的是：向量化通常比显式循环更高效；广播规则不熟容易导致维度不匹配；大数组操作要关注内存；视图与副本行为不同；dtype 选择会影响内存和速度。
reStructuredText 风格
reStructuredText 是 Sphinx 等 Python 文档工具链常用的轻量标记语言。它适合编写项目文档、API 文档，并可转换为 HTML、LaTeX 等格式。使用时注意缩进一致、空行分隔结构、标题下划线长度不小于标题文本长度，特殊符号需要转义时用反斜杠。
主标题
======
二级标题
--------
* 项目符号列表
* 第二个项目
1. 数字列表
2. 第二项
代码块::
def example():
print('使用4空格缩进')
.. note::
这是一个提示框
`超链接 <https://python.org>`_
表格可以用 RST 表格语法；跨文档链接可用 :doc:`other_page` 或 :ref:`section-label`。
Epytext 风格
Epytext 是 Epydoc 工具默认支持的 docstring 标记格式，使用 @、L{} 等符号标注参数、返回值、异常等元素。标记符号应紧跟在行首或前导空格后，类型说明可选。它与 reStructuredText 的一个明显区别是使用 @ 而不是 : 作为标记前缀。
def calculate_area(width, height):
'''
Calculate the area of a rectangle.
@param width: The width of the rectangle (in meters)
@type width: float
@param height: The height of the rectangle (in meters)
@type height: float
@return: The calculated area
@rtype: float
@raise ValueError: If either dimension is negative
'''
if width < 0 or height < 0:
raise ValueError('Dimensions cannot be negative')
return width * height
总结
Python 注释规范的核心不是写得多，而是写得准。单行注释用 #，多行说明可用三引号但要知道它本质是字符串；函数、类、模块优先写 docstring，并能被 help()、__doc__、Sphinx 等工具读取。内容上要避免废话、过度注释和注释与代码不同步。风格上可遵循 PEP 257，并在 Google、NumPy、reStructuredText、Epytext 等常用格式中选择团队统一方案。
Re: Python单行多行注释与docstring规范写法
整理得挺系统，尤其把三引号本质是字符串、和真正 docstring 的区别讲清楚了，这点很多人容易混。函数、类、模块 docstring 的位置，以及 __doc__、help()、pydoc、Sphinx 这些用途也写得很实用。单行注释 # 后加空格、不要写废话注释、代码块注释要和代码同步更新，这些都是平时容易忽略的细节。行内注释部分好像还没展开，期待补上。整体看这套规范可以直接拿来当团队约定，收藏了。Re: Python单行多行注释与docstring规范写法
楼主这篇整理得挺系统的，尤其是三引号本质是字符串、只有定义在函数类或模块开头的第一个三引号才会成为 docstring 这个点，很多初学者确实容易搞混。单行注释 # 后加空格、docstring 第一行简短描述再空一行写详细说明，这些细节在团队协作和代码审查里很影响可读性。我自己写的时候会尽量把参数、返回值和可能抛出的异常写进 docstring，类型注解能表达清楚的地方就少写重复说明，这样 IDE 提示和文档生成工具都能兼顾。另外想问一下，行内注释那部分是不是还没发完？还有模块 docstring 里写作者和更新日期，如果项目用 Git 管理，会不会和提交记录有点重复？期待后续补充。Re: Python单行多行注释与docstring规范写法
这篇整理挺实用的，三引号本质是字符串、只有定义后第一个三引号字符串会成为 docstring 这点讲得很清楚，容易踩坑。函数、类、模块的 docstring 示例也直观，尤其是参数、返回值、异常分开写，对后面生成文档和 IDE 提示确实友好。单行注释 # 后加空格、少写废话注释、代码块注释要和代码同步更新，这几条很认同。最后行内注释部分好像只写了个标题，期待补完，比如和代码的间距、注释长度、什么时候适合写行内注释。整体已经很像一份能直接放进团队规范里的草稿了。
页:
[1]