在 Python 3 中，注释是提高代码可读性、可维护性以及团队协作效率的重要工具。Python 的注释机制简单直观，但也有一些需要特别注意的细节和最佳实践。
以下是 Python 3 注释的全面指南：
1. 单行注释
使用井号 # 开头。# 后面的所有内容直到行尾都会被 Python 解释器忽略。
# 这是一个独立的单行注释
print("Hello, World!") # 这也是注释，通常放在代码同一行，与代码保持至少两个空格的距离
# 注释可以用来临时禁用（注释掉）某行代码
# print("这行代码不会执行")💡 技巧：在绝大多数现代编辑器（如 VS Code, PyCharm）中，选中代码后按 Ctrl + / (Windows/Linux) 或 Cmd + / (Mac) 可以快速添加或取消单行注释。
2. 多行注释
注意：Python 实际上没有专门的多行注释语法（像 C/Java 的 /* ... */）。
但在实际开发中，我们通常用以下两种方式实现多行注释的效果：
方式 A：连续使用多个 # (最推荐)
这是 PEP 8 (Python 官方代码风格指南) 推荐的做法，因为它是真正的注释，不会在内存中创建字符串对象。
# 这是一个多行注释的第一行
# 这是第二行
# 这是第三行
x = 10方式 B：使用未赋值的三引号字符串 (''' 或 """)
如果一段多行字符串没有被赋值给任何变量，Python 解释器在解析时会将其忽略，因此常被用作多行注释。
"""
这是一个使用三引号的多行注释。
它常用于临时屏蔽大段代码，
或者在文件开头写简单的说明。
"""
y = 20⚠️ 注意：如果三引号字符串被赋值给了变量（如 doc = """..."""），或者放在了函数/类的正下方，它就不再是注释，而是文档字符串 (Docstring)。
3. 文档字符串 (Docstrings) 🌟 核心特性
Docstring 是 Python 独有的强大功能。它是写在模块、类、函数或方法定义正下方的第一个字符串，通常使用三个双引号 """ 包裹。
它的主要作用是自动生成文档。你可以通过内置的 help() 函数或对象的 .__doc__ 属性来读取它。
def calculate_area(radius: float) -> float:
"""
计算圆的面积。
参数:
radius (float): 圆的半径，必须大于 0。
返回:
float: 圆的面积 (π * r^2)。
异常:
ValueError: 如果半径小于或等于 0 时抛出。
"""
if radius <= 0:
raise ValueError("半径必须大于 0")
return 3.14159 * (radius ** 2)
# 查看文档字符串
print(calculate_area.__doc__)
# 或者在交互式环境中使用: help(calculate_area)(注：Docstring 的格式有多种规范，如 Google Style, NumPy Style, Sphinx/reST。上述示例接近 Google Style，是目前最易读和流行的格式。)
4. 特殊标记注释 (IDE 友好)
在团队开发中，我们经常在注释中使用全大写的特定关键词。现代 IDE（如 PyCharm, VS Code）会自动识别这些词，并在侧边栏高亮显示或列入任务列表：
TODO：表示这里还有未完成的工作，需要后续处理。# TODO: 优化此处的数据库查询逻辑
FIXME：表示这里的代码已知有缺陷或会报错，需要尽快修复。# FIXME: 当输入为负数时，此函数会崩溃
XXX或HACK：表示这里的代码实现很丑陋或使用了非标准技巧，虽然能工作，但未来需要重构。# HACK: 为了兼容旧版 API，强制转换了数据类型
NOTE：用于提醒其他开发者注意某些重要的细节或副作用。# NOTE: 此函数会修改传入的列表对象本身
5. 注释的最佳实践 (PEP 8 规范)
- 注释应该解释“为什么 (Why)”，而不是“是什么 (What)”
- ❌ 坏注释：
x = x + 1 # 将 x 加 1(代码已经很清楚说明了是什么) - ✅ 好注释：
x = x + 1 # 补偿由于网络延迟导致的索引偏移(解释了业务逻辑和原因)
- 保持注释与代码同步
- 如果你修改了代码的逻辑，务必同时更新注释。过时的注释比没有注释更具误导性。
- 使用完整的句子
- 块注释和文档字符串应使用完整的句子，首字母大写，标点符号结尾（除非是极短的短语）。
- 优先写出“自文档化”的代码
- 最好的注释是清晰的变量名和函数名。如果代码需要大量注释才能看懂，通常意味着代码结构需要重构。
- ❌
def p(d): ... # p 代表 process, d 代表 data - ✅
def process_user_data(user_data): ...
6. 现代 Python 的补充：类型提示 (Type Hints)
从 Python 3.5 开始引入的类型提示，在很大程度上减少了对传统注释的依赖。它直接告诉阅读者（和 IDE）变量或返回值的预期类型。
# 传统方式：依赖注释说明类型
def greet(name, age):
# name 是字符串, age 是整数
return f"{name} is {age}"
# 现代 Pythonic 方式：使用类型提示 (Type Hints)
def greet(name: str, age: int) -> str:
return f"{name} is {age}"类型提示不仅让代码更清晰，还能让 IDE 提供更强大的自动补全和静态类型检查（如使用 mypy 工具）。
💡 总结
- 用
#写单行或块注释。 - 用
"""..."""写模块、类和函数的 Docstring。 - 使用
TODO/FIXME标记技术债务。 - 代码告诉你怎么做 (How)，注释告诉你为什么这么做 (Why)。
如果你对如何编写规范的 Docstring（如 Google 风格 vs Sphinx 风格），或者如何配置类型检查工具感兴趣，可以随时告诉我！