在编程中,注释是程序员写给人看，而不是给计算机看的说明文字，Python 解释器会完全忽略注释的内容，它们的存在纯粹是为了提高代码的可读性和可维护性。
（图片来源网络，侵删）
下面我将为你详细、系统地讲解 Python 注释的方方面面。
为什么需要注释？（注释的重要性）
- 解释代码：当你的代码逻辑比较复杂，或者使用了某些巧妙但不直观的技巧时，注释可以帮助其他开发者（或者未来的你）快速理解代码的意图。
- 标记待办事项：在开发过程中，可以用注释来标记一些还没完成、需要改进或有问题的代码块，方便后续跟进。
- 生成文档：通过特定的注释格式（如 Docstring），可以自动生成项目的文档，这是 Python 的一个强大特性。
- 临时禁用代码：在调试时，可以临时将某一行或几行代码注释掉，来排查问题，而无需真正删除它们。
Python 注释的两种主要形式
Python 主要支持两种注释：单行注释和多行注释（也称为文档字符串）。
单行注释
单行注释以井号 开头，直到该行末尾。
特点：
（图片来源网络，侵删）
- 只能注释一行。
- 后面需要至少跟一个空格，这是 PEP 8（Python 官方代码风格指南）推荐的规范。
- 如果想注释多行,需要在每一行都加上 。
示例：
# 这是一个简单的单行注释，解释下面这行代码的作用
# 计算圆的面积
radius = 10
pi = 3.14159
area = pi * (radius ** 2)
# 也可以在代码行末尾添加注释，解释该行
# 但请注意，注释应该简短，不要让一行变得过长
circumference = 2 * pi * radius # 计算圆的周长
# 如果想注释多行，每一行都需要 #
# 这是一个
# 多行注释
# 通过单行注释实现
# print("这行代码被注释掉了，不会执行")
多行注释 / 文档字符串
Python 中没有像 C++ () 那样的多行注释符号，所谓的“多行注释”通常使用文档字符串来实现。
什么是文档字符串？ 文档字符串是字符串字面量，它出现在模块、函数、类或方法的定义下方，用三重双引号 或三单引号 括起来。
特点：
（图片来源网络，侵删）
- 它们不仅仅是注释,它们是代码的一部分，是对象的一个属性（可以通过
__doc__属性访问）。 - 它们是 Python 标准库中
help()函数和文档生成工具（如 Sphinx）的主要信息来源。 - 用来解释模块、类、函数的整体功能、参数、返回值等。
示例：
def greet(name):
"""
这是一个函数的文档字符串。
它用于向指定的人问好。
参数:
name (str): 要问候的人的名字。
返回:
str: 一个包含问候语的字符串。
"""
return f"Hello, {name}!"
# 调用函数
greeting_message = greet("Alice")
# 查看函数的文档字符串
print(greet.__doc__)
# 输出:
# 这是一个函数的文档字符串。
# 它用于向指定的人问好。
#
# 参数:
# name (str): 要问候的人的名字。
#
# 返回:
# str: 一个包含问候语的字符串。
# 在交互式环境中，输入 help(greet) 也会显示这个文档字符串
对于普通代码块的多行注释： 虽然不推荐，但你也可以用三引号来写一个真正的“多行注释”，因为它没有被赋值给任何变量，Python 解释器会忽略它，但这通常被认为是滥用文档字符串。
# 不推荐这样做，因为它不是真正的文档字符串 """ 这是一个普通的代码块， 我们想在这里写一些多行的说明。 """ x = 1 y = 2 # ...
推荐的写法：还是使用多个单行注释。
# 这是一个代码块的开头 # 我们在这里做一些初始化操作 # 需要说明一下这个逻辑的背景... x = 1 y = 2 # ...
最佳实践和规范
遵循良好的注释规范,能让你的代码更专业、更易读。
-
注释要解释“为什么”，而不是“是什么”
- 差：
x = 10 # 把 x 赋值为 10(废话) - 好：
x = 10 # 设置最大用户数量，防止内存溢出
- 差：
-
保持注释简洁明了
注释应该简短,一针见血，避免冗长和模糊不清的描述。
-
及时更新注释
- 当你修改代码时,一定要同步更新相关的注释。过时、错误的注释比没有注释更有害，因为它会误导阅读者。
-
使用文档字符串记录公共接口
对于所有公共的模块、类和函数，都应该编写清晰的文档字符串，这包括函数的功能、参数、返回值、可能抛出的异常等。
-
避免过度注释
- 对于一目了然的代码（如
a = b + c），不需要添加注释，过多的注释会让代码变得臃肿。
- 对于一目了然的代码（如
-
为复杂的算法或逻辑块添加注释
当你实现了一个复杂的算法或一段巧妙的逻辑时,一定要在代码上方或旁边添加注释，解释其工作原理。
| 特性 | 单行注释 | 文档字符串 |
|---|---|---|
| 符号 | 或 | |
| 作用 | 解释一行代码或一小段逻辑 | 解释模块、类、函数的整体功能、参数、返回值 |
| 位置 | 行首或行末 | 模块、类、函数定义的下方第一行 |
| 访问方式 | 不可通过程序访问 | 可通过 obj.__doc__ 访问，是对象的一部分 |
| 用途 | 日常代码解释、临时禁用代码 | 生成官方文档、提供 help() 信息 |
核心思想：代码是写给人看的，顺便能让机器执行。 注释是连接你（作者）和未来的阅读者（包括你自己）的桥梁，养成写好注释的习惯，是成为一名优秀 Python 开发者的关键一步。
