Python注释三种写法：单行、多行、文档注释及PEP8实践

脚本专家

在Python开发中，注释是提升代码可读性、降低维护成本的关键手段。无论是新手练习还是企业级项目，规范使用注释都是一项必备技能。本文将详细介绍Python单行注释、多行注释和文档注释的写法、快捷键、常见坑点以及PEP8规范，帮助你在实际编码中写出清晰、规范的注释。

[strong]一、注释的作用与适用场景[/strong]

注释不会被执行，仅用于开发者阅读。主要作用包括：快速理解代码逻辑、方便后期迭代和Bug修复、提高团队协作效率、辅助调试（临时屏蔽代码）。常见场景有：新手练习标注思路、函数/类核心功能说明、临时屏蔽测试代码、生成项目文档等。

[strong]二、单行注释（

2. #

复制代码

）[/strong]

单行注释以井号开头，从

2. #

复制代码

到行末均为注释。可以独占一行，也可以放在代码行末尾。

示例：

2. # 定义用户名
3. username = "Python学习者"
4. # 定义年龄
5. age = 25
6. # 输出信息
7. print(f"用户：{username}，年龄：{age}")  # 行尾注释：打印用户基础信息

复制代码

注意事项：行尾注释前应空两个空格，符合PEP8规范。简单代码无需过度注释，复杂逻辑才需添加说明。

[strong]三、多行注释（三引号）[/strong]

Python没有专属多行注释语法，通常使用单引号或双引号的三引号包裹多行文本。

语法：

2. '''
3. 多行注释内容
4. '''
5. 或
6. """
7. 多行注释内容
8. """

复制代码

示例：

2. '''
3. 功能：计算两个数字的和
4. 作者：Python学习者
5. 时间：2026-05-30
6. '''
7. def add_num(a, b):
8.     return a + b
10. """
11. 双三引号也可批量屏蔽测试代码
12. print("测试代码1")
13. print("测试代码2")
14. """
15. print(add_num(10, 20))

复制代码

注意：三引号注释内部不能嵌套同类型三引号，否则会报错。若需嵌套，使用转义符或换成不同的引号类别。

[strong]四、文档注释（标准文档字符串）[/strong]

文档注释是规范化的多行注释，必须放在函数、类或模块的第一行，使用双三引号。它可用于通过工具（如Sphinx）自动生成文档。

模块文档示例：

2. """
3. 基础计算模块
4. 功能：实现加减乘除基础运算
5. 作者：Python学习者
6. 版本：1.0
7. """
8. print("基础计算模块加载完成")

复制代码

函数文档注释（推荐企业写法）：

2. def calculate_avg(num_list):
3.     """
4.     计算数字列表的平均值
6.     Args:
7.         num_list (list): 传入数字列表
9.     Returns:
10.         float: 返回列表平均值，空列表返回0
11.     """
12.     if not num_list:
13.         return 0
14.     return sum(num_list) / len(num_list)
16. print(calculate_avg([85, 90, 88]))

复制代码

类文档注释：

2. class Student:
3.     """
4.     学生信息管理类
5.     实现学生成绩添加、平均分计算功能
6.     """
7.     def __init__(self, name, age):
8.         """
9.         初始化学生信息
11.         Args:
12.             name (str): 学生姓名
13.             age (int): 学生年龄
14.         """
15.         self.name = name
16.         self.age = age
17.         self.grades = []
19.     def add_grade(self, grade):
20.         """添加学生成绩"""
21.         self.grades.append(grade)

复制代码

[strong]五、编辑器快捷键[/strong]

提高注释效率推荐掌握以下快捷键：

• PyCharm / VS Code：选中代码后按
  2. Ctrl + /

  复制代码
  批量单行注释或取消注释。
  
• VS Code 多行注释：
  2. Shift + Alt + A

  复制代码
  。
  
• IDLE：
  2. Alt + 3

  复制代码
  注释，
  2. Alt + 4

  复制代码
  取消注释。
  

[strong]六、常见问题与避坑[/strong]

1. 注释嵌套报错：三引号注释内部不能出现相同三引号文本。解决方案：改用单三引号与双三引号错开，或使用转义。
2. 过度注释：简单代码（如

2. a = 10

复制代码

）无需注释，否则影响阅读。核心逻辑才需详细说明。
3. 行尾注释间距：PEP8要求代码与注释之间空两个空格，例如：

2. print("hello")  # 输出问候

复制代码

。
4. 文档注释缺失：函数、类、模块应标配文档注释，参数和返回值描述清晰。
5. 敏感信息泄漏：注释中禁止记录密码、密钥、接口Token等。
6. 注释与代码不一致：迭代代码时必须同步更新注释，避免误导。
7. 废弃代码应删除，不要用注释保留，否则造成冗余。

[strong]七、PEP8注释规范[/strong]

• 单行注释：
  2. #

  复制代码
  后必须加一个空格。
  
• 独立行注释：用于解释下一段代码，避免空注释。
  
• 文档注释：使用双三引号，参数和返回值清晰说明。
  
• 注释语言统一：项目中统一使用中文或英文，不要混用。
  

核心口诀：简单代码不注释，复杂逻辑详注释，业务功能必注释，冗余代码不瞎注。

掌握这三类注释写法并遵循PEP8规范，你的Python代码在可读性、可维护性和团队协作方面都会大幅提升。

热心网友4

感谢楼主的详细总结！刚学Python时确实经常分不清多行注释和文档注释的用法，看了你的整理清晰多了。特别喜欢那个“简单代码不注释，复杂逻辑详注释”的口诀，很实用。另外请教一下：文档注释里参数和返回值的格式（比如Args:、Returns:）是不是有官方推荐的风格？还是说团队统一就好？

热心网友4

楼主的总结非常全面，从基础写法到PEP8规范再到常见坑点都覆盖了，对新手和老手都有参考价值。特别赞同“简单代码不注释，复杂逻辑详注释”这个口诀，很多初学者容易走极端要么不写注释要么每行都写。另外文档注释的Args/Returns格式确实是团队协作和自动生成文档的好做法。想请教一下，在项目实践中，对于临时屏蔽代码，楼主更推荐用三引号还是直接用`#`逐行注释？有没有遇到过因为三引号嵌套导致的问题？

热心网友4

谢谢楼主的详细总结，非常实用！尤其是文档注释那部分，很多新手容易把三引号当作普通多行注释来用，忘了它还能通过工具生成文档。另外关于行尾注释的空格规范，我以前经常忽略，现在养成习惯后代码整洁多了。想请教一下：在写函数文档注释时，参数类型和返回值的描述是必须严格按照某种格式（比如Google风格）还是只要团队内部统一就行？