目录

• 一、基础注释类型
  • 二、特殊注释场景
  • 三、注释规范（PEP 8）
  • 四、常见问题解决
  • 五、注释最佳实践
  • 六、趣味注释示例（来自网络）

---

参考

• Python代码注释9种方式，Python怎么注释一段代码！ (opens new window)
• Python注释的使用方法（详解） (opens new window)
• python 单行注释 多行注释 批量注释 中文注释 (opens new window)

---

Python：代码注释

一、基础注释类型

1. 单行注释

• 语法：以 # 开头，后接注释内容。

• 用途：解释单行代码或简短说明。

• 示例：

  a = 5  # 初始化变量a为5
  

2. 多行注释（块注释）

• 语法：使用三个单引号 ''' 或三个双引号 """ 包裹多行文本。

• 用途：解释复杂逻辑、代码块功能或文件版权信息。

• 示例：

  '''
  初始化用户数据：
  - 用户ID
  - 用户名
  - 邮箱
  '''
  user_id = 101
  user_name = "Alice"
  

3. 文档字符串（Docstrings）

• 语法：函数/类定义后的第一行用 """ 包裹的描述文本。

• 用途：自动生成API文档（通过 help() 或工具如Sphinx查看）。

• 规范：

  • 描述功能、参数、返回值。
  • 遵循 PEP 257 规范。

• 示例：

  def add(a, b):
      """
      计算两数之和。
      参数:
        a (int): 第一个加数
        b (int): 第二个加数
      返回:
        int: a与b的和
      """
      return a + b
  

4. 内联注释

• 语法：与代码同行，在语句后以 # 开头。

• 规范：

  • 与代码至少间隔两个空格。
  • 避免描述显而易见的内容（如 x = x + 1 # 增加x）。

• 示例：

  result = fetch_data()  # 从API获取数据，需处理超时
  

---

二、特殊注释场景

1. 标记注释（TODO/BUG）

• 用途：标记待办项或已知问题，便于团队追踪。

• 示例：

  # TODO: 添加数据验证逻辑
  # BUG: 输入负数时计算结果异常
  

2. 中文注释与编码声明

• 问题：文件含中文时需声明编码，否则可能乱码。

• 解决方案

  ：在文件开头添加以下之一：

  # -*- coding: utf-8 -*-
  # coding=utf-8
  

• 注意：Python 3 默认UTF-8，但显式声明可避免跨环境问题。

3. 调试注释

• 临时禁用代码：用 # 注释多行代码（IDE快捷键如Ctrl+/）。
• 替代方案：使用 if False: 包裹代码块（避免嵌套注释问题）。

---

三、注释规范（PEP 8）

1. 准确性：注释需与代码逻辑一致，修改代码时同步更新注释。
2. 简洁性：
   • 避免冗余（如 # 赋值给变量x）。
   • 块注释每行以 # 加一个空格开头。
3. 语法规范：
   • 完整句子首字母大写。
   • 英文注释优先（除非团队明确使用中文）。
4. 位置要求：
   • 函数文档字符串在定义后首行。
   • 避免分隔关键字（如 height = float(# 错误位置)。

---

四、常见问题解决

1. 中文乱码

• 场景：代码含中文时运行报错 SyntaxError: (unicode error)。
• 解决步骤：
  1. 文件开头添加 # coding=utf-8。
  2. IDE设置文件编码为UTF-8（PyCharm：File → Encoding → UTF-8）。
  3. 避免路径含中文。

2. 嵌套注释无效

• 问题：多行注释不支持嵌套（如 ''' 外层 ''' 内层 ''' 会报错）。

• 替代方案：内部用单行注释：

  '''
  外层注释...
  # 内层注释
  '''
  

---

五、注释最佳实践

1. 写什么？

   • 解释为何（Why）：复杂算法、设计决策（如 # 因性能问题选择递归）。
   • 标记待办项：# TODO: 优化算法复杂度。
   • 警告隐患：# 注意：此方法非线程安全。

2. 避免什么？

   • 描述代码行为（如 # 循环10次）。
   • 情绪化内容（如 # 这段代码太烂了！）。

3. 工具支持：

   • 用 __doc__ 属性访问文档字符串：

     print(add.__doc__)  # 输出函数的文档说明
     

   • IDE块注释：PyCharm支持选中代码后批量注释（Ctrl+/）。

---

六、趣味注释示例（来自网络）

# 1. 只有上帝知道
# 我写这一行时，只有上帝和我知道我在写什么
# 现在，只有上帝知道了

# 2. 时空对话
# somedev1 - 2002/6/7：临时添加登录追踪
# somedev2 - 2007/5/22：临时个屁！

# 3. 魔法警告
# 有魔法，别碰！

重要提醒：幽默注释需谨慎，避免影响团队协作或代码维护。

---

通过合理使用注释，可显著提升代码可读性和可维护性。遵循PEP 8规范，结合团队约定，让注释成为高效开发的助力而非负担。