Python 注释

Python 注释详解

注释是编程中非常重要的部分，它能帮助开发者理解代码的功能和逻辑。Python 提供了多种注释方式：

1. 单行注释

使用 # 符号开头，从 # 开始到行尾的内容都会被 Python 解释器忽略。

# 这是一个单行注释
x = 5  # 这也是注释，可以跟在代码后面

2. 多行注释

Python 没有专门的多行注释语法，但可以通过以下方式实现：

方法1：每行使用

# 这是多行注释的第一行
# 这是第二行
# 这是第三行

方法2：使用三引号字符串（虽然不是真正的注释，但能达到同样效果）

"""
这是一个多行"注释"
Python 会将其视为字符串
但不会赋给任何变量
所以不会被执行
"""

3. 文档字符串 (Docstring)

文档字符串是 Python 特有的功能，用于模块、函数、类或方法的说明，使用三引号("""或''')包围。

def add(a, b):
    """
    这个函数用于计算两个数的和
    
    参数:
        a (int/float): 第一个数字
        b (int/float): 第二个数字
    
    返回:
        int/float: 两个数字的和
    """
    return a + b

可以通过 help(add) 或 add.__doc__ 查看这个文档字符串。

4. 特殊注释

编码声明注释（必须放在文件第一行或第二行）

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

解释器路径注释（用于 Unix/Linux 系统）

#!/usr/bin/env python3

5. 注释的最佳实践

解释为什么，而不是做什么 - 代码本身已经显示了做什么，注释应该解释为什么这样做
```
# 不好: 计算总和
total = price * quantity
   
# 好: 应用95折优惠
total = price * quantity * 0.95
```

避免过度注释 - 清晰的代码胜过大量注释

# 不好:
x = x + 1  # 给x加1
   
# 好:
# 补偿数组的0-based索引
position = index + 1

及时更新注释 - 修改代码时记得更新相关注释
使用一致的注释风格 - 团队中保持统一的注释格式

6. 注释的常见用途

标记待办事项

# TODO: 添加错误处理
# FIXME: 这里的算法需要优化

调试时临时禁用代码

# print("调试信息")  # 暂时禁用这行

解释复杂算法

# 使用快速排序算法，因为数据集可能很大
result = sorted(data, key=lambda x: x[1])

注释是编写可维护代码的重要组成部分，良好的注释习惯可以显著提高代码的可读性和可维护性。