为什么注释在Python中如此重要？

注释不仅帮助他人理解你的代码，也是几个月后自己回顾代码时的"路标"。Python注释的主要作用包括：

• 解释复杂代码段的逻辑
• 描述函数/类的用途和参数
• 临时禁用代码（调试）
• 提供使用示例
• 记录代码修改历史

1. 单行注释

单行注释以井号(#)开始，适用于简短说明：

# 计算用户年龄（单行注释示例）
age = current_year - birth_year

# 下面的代码暂时被禁用
# print("调试信息：", variables)

最佳实践：

• 注释应写在代码上方或行末（与代码至少间隔两个空格）
• 避免显而易见的注释（如# 设置变量x为5）
• 保持简洁，一行不超过79个字符

2. 多行注释

Python没有专门的多行注释语法，但可以使用连续的井号或三引号字符串：

# 这是使用多个单行注释
# 实现的多行注释示例
# 每行都需要以井号开头

"""
使用三引号的多行注释
常用于模块顶部的描述
注意：这实际上是字符串，但未被赋值给变量
"""
'''也可以用三个单引号'''

使用建议：

• 文件顶部的模块描述推荐使用三引号
• 代码中的长说明建议使用多个单行注释
• 避免在函数内使用三引号作为注释（会被视为文档字符串）

3. 文档字符串（Docstrings）

文档字符串是Python特有的功能，用于模块、函数、类或方法的说明：

def calculate_average(numbers):
    """
    计算数字列表的平均值
    
    参数:
    numbers (list): 包含数字的列表
    
    返回:
    float: 输入列表的平均值
    
    示例:
    >>> calculate_average([1, 2, 3, 4])
    2.5
    """
    return sum(numbers) / len(numbers) if numbers else 0

文档字符串规范：

• 使用三重双引号 """
• 第一行是简要描述（不以句号结束）
• 空一行后写详细描述
• 包含参数说明、返回值和示例
• 可通过__doc__属性或help()函数访问

Python注释最佳实践

# ✅ 好的注释示例
# 使用快速排序因为输入数据可能部分有序
# 这比归并排序节省约15%内存

# ❌ 不好的注释示例
# 设置x为5
x = 5

掌握Python注释的艺术

良好的注释习惯是专业Python开发者的标志。记住：
"代码说明怎么做，注释说明为什么"

通过本教程，您已经学会了：