Python注释完全指南：提升代码可读性与维护性

为什么注释如此重要？

• 提高可读性：让其他开发者（或未来的你）更容易理解代码
• 解释复杂逻辑：说明代码中难以理解的部分
• 文档生成：使用文档字符串自动生成API文档
• 调试辅助：临时禁用代码而不删除
• 团队协作：在团队项目中提供重要上下文

Python注释的三种主要类型

1. 单行注释

使用井号(#)创建单行注释，适用于简短说明：

# 计算矩形面积
length = 10
width = 5
area = length * width  # 计算面积
print(area)  # 输出结果

2. 多行注释

使用三引号('''或""")创建多行注释，适用于长段说明：

'''
这个函数计算两个数的乘积
参数:
  a (int): 第一个数字
  b (int): 第二个数字
返回:
  int: a和b的乘积
'''
def multiply(a, b):
    return a * b

3. 文档字符串（Docstrings）

使用三引号在模块、函数、类或方法开头添加文档字符串，可以通过help()函数访问：

def calculate_discounted_price(price, discount):
    """
    计算商品折扣后的价格
    
    参数:
        price (float): 商品原价
        discount (float): 折扣率(0-1之间的小数)
        
    返回:
        float: 折扣后的价格
        
    示例:
        >>> calculate_discounted_price(100, 0.2)
        80.0
    """
    return price * (1 - discount)

Python注释最佳实践

注释实用示例

良好注释示例

def fibonacci(n):
    """
    计算斐波那契数列的第n项
    
    参数:
        n (int): 要计算的项数(非负整数)
        
    返回:
        int: 斐波那契数列的第n项
        
    注意:
        使用迭代方法而非递归，以提高效率
    """
    if n <= 0:
        return 0
    elif n == 1:
        return 1
        
    # 初始化前两个斐波那契数
    a, b = 0, 1
    
    # 从第2项开始迭代计算
    for _ in range(2, n + 1):
        # 使用元组解包同时更新a和b的值
        a, b = b, a + b
        
    return b

应避免的注释示例

# 不好的注释示例

# 设置x为5
x = 5

# 增加x的值
x = x + 1  # 这很明显，不需要注释

'''
这个函数做了一些事情
参数：a，b
返回：一些值
'''
def func(a, b):
    # 复杂的代码但没有解释
    return (a ** 2) + (b * 3) - 17  # 没有说明为什么这样计算

特殊注释类型

TODO注释

标记需要后续完成的工作：

# TODO: 添加输入验证
# TODO: 优化算法效率

调试注释

临时禁用代码段：

# 调试时启用
# print("变量值:", variable)

# 正式版本中禁用
# process_data()

总结：有效注释的艺术