刚接触python的人往往只会用井号写注释，遇到需要注释大段代码时就不知道该怎么办了。其实python的注释体系比想象中丰富，除了单行注释，还有多行注释的写法、专门用于文档说明的docstring，以及一些有特殊用途的声明式注释。搞清楚它们的区别和使用场景，是写出规范python代码的第一步。下面就来逐一讲解。
单行注释：井号是唯一的主角
python中真正意义上的注释只有一个符号，就是井号#。解释器遇到#后，会忽略该行从井号开始到行尾的所有内容，这些内容不会参与任何执行逻辑。这是python官方定义的唯一注释方式，无论什么场景，单行注释都必须以#开头。
单行注释有两种常见位置：一种是独占一行，写在代码上方，用来解释接下来这段代码的作用；另一种是写在代码行尾，与语句保持在同一行，用来补充说明。PEP 8规范建议，行尾注释与代码之间至少间隔两个空格，井号后也要有一个空格，例如x = x + 1 # 累加计数器这样的写法才是推荐的格式。
# 这是独占一行的注释，解释下面的函数作用
def calculate_area(radius):
# 圆周率取近似值
pi = 3.14159
return pi * radius ** 2 # 行尾注释：计算圆的面积需要特别注意的一点是，#只能注释一行。如果你用记事本打开别人的代码，看到大段被注释的内容，那并不是某种块注释语法，而是多行连续使用井号，或者借助了其他手段，这就引出了下一节的话题。
多行注释：三引号字符串的"伪装术"
很多教程会说python支持三引号多行注释，严格来讲这个说法并不准确。三引号（'''或"""）包裹的内容其实是一个字符串表达式，它之所以看起来像注释，是因为这个字符串没有被赋值给任何变量，解释器会直接丢弃它，不产生任何副作用。
"""
这一整段看起来像注释
实际上是一个字符串字面量
解释器会创建它然后立即丢弃
"""
print("hello")
'''
用三个单引号也是同样的效果
'''这种写法能起到注释的视觉效果，但它和井号注释有本质区别：井号注释在词法分析阶段就被丢弃，而三引号字符串是真实存在的对象，会占用内存，如果写在函数内部还会影响该函数的常量缓存。更重要的是，如果三引号字符串出现在函数、类或模块的第一个语句位置，它就不是注释了，而是docstring，会被解释器收集起来存入__doc__属性。
因此PEP 8明确建议：块注释应该用连续的井号书写，而不是依赖三引号字符串。临时注释掉一大段代码调试时可以偷懒用三引号，但如果被注释的代码里本身包含三引号字符串，就会导致语法错误，这也是它的一个隐藏陷阱。
文档字符串：python独有的注释体系
docstring是python中非常特殊的存在，它是写在模块、函数、类定义第一行的字符串，用三引号包裹，作用是描述这个对象的用途、参数和返回值。它与普通注释最大的区别在于它是可访问的运行时数据，可以通过__doc__属性或内置函数help()读取，很多文档生成工具比如Sphinx也是基于它来构建文档的。
def divide(a, b):
"""计算两个数相除的结果。
参数:
a: 被除数
b: 除数，不能为零
返回:
a 除以 b 的商
异常:
ZeroDivisionError: 当 b 为零时抛出
"""
if b == 0:
raise ZeroDivisionError("除数不能为零")
return a / b
# 通过 __doc__ 属性访问文档字符串
print(divide.__doc__)
# 调用 help 函数查看格式化后的帮助信息
help(divide)按照惯例，模块级docstring写在文件最开头，说明整个模块的功能；函数和类的docstring写在其定义的第一行，用一句话概括功能，必要时再展开参数说明。业界有Google风格、NumPy风格等多种书写格式，团队协作时统一采用一种即可。docstring写得好，IDE的悬停提示就能直接展示函数说明，调用者不需要翻源码。
两种有特殊用途的声明式注释
除了普通注释，还有两类写在文件开头的井号注释具有特殊功能，容易被初学者忽略。第一类是编码声明，写在python文件的第一行或第二行，格式如# -*- coding: utf-8 -*-，用于告诉解释器该源文件使用的字符编码。python 3默认源文件编码就是utf-8，所以现在很少需要显式声明，但在维护一些老项目或处理特殊编码文件时仍会见到。
第二类是shebang行，也叫解释器指令，写作#!/usr/bin/env python3。它用在类Unix系统上，当脚本被赋予可执行权限后，系统内核会根据这一行自动找到python解释器来执行脚本。env python3的写法比硬编码路径更通用，因为它会去环境变量PATH中查找解释器位置，避免不同机器安装路径不一致导致脚本无法运行。
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""这个文件同时演示了 shebang 行和编码声明"""
if __name__ == "__main__":
print("特殊注释行示例")这两行的顺序也有讲究：shebang必须是第一行，否则不会被系统识别；编码声明可以紧跟其后放在第二行。在Windows上shebang虽然不生效，但保留它不影响运行，也便于脚本跨平台使用。
编写注释的实用技巧与建议
知道了注释的种类，还要知道怎么用好它们。首先遵循一个原则：注释解释为什么这么做，而不是复述代码做了什么。像i += 1 # i加1这种注释毫无价值，而# 兼容旧接口，v2版本会移除这样的注释能传达代码之外的关键信息。过时的注释比没有注释更可怕，修改代码时记得同步更新注释。
其次善用工具能大幅提升效率。主流编辑器都提供了注释快捷键，比如PyCharm和VS Code中都用Ctrl+/code>切换行注释，选中多行后一键批量添加或取消井号，比手动敲三引号规范得多。版本控制工具也提供了替代方案，如果只是想临时停用一段代码，用git分支管理往往比堆注释更干净。
最后把握一个度：注释不是越多越好。函数命名清晰、结构简单的代码本身就具有自解释性，这时候强行加注释反而显得冗余。把详细的参数说明交给docstring，把设计决策交给块注释，把琐碎的临时说明在提交代码前清理掉，这样的注释习惯才能让代码在半年后依然容易维护。
python注释python多行注释python文档字符串修改时间：2026-09-15 22:38:50