注释

注释是用于解释代码的文本，不会被 Python 解释器执行。良好的注释可以提高代码的可读性和可维护性。

单行注释

使用 # 符号创建单行注释。

# 这是一个单行注释
print("Hello, World!")  # 这也是注释

# 计算两个数的和
a = 10
b = 20
c = a + b  # 将 a 和 b 相加
print(c)  # 输出结果

多行注释

使用多个 #

# 这是第一行注释
# 这是第二行注释
# 这是第三行注释
print("多行注释示例")

使用三引号

"""
这是一个多行注释
可以写多行内容
Python 会忽略这些内容
"""
print("使用三引号的注释")

'''
这也是一个多行注释
使用单引号的三引号
'''
print("使用单引号的三引号")

文档字符串（Docstring）

文档字符串是用于描述模块、函数、类或方法的字符串，通常使用三引号。

模块文档字符串

"""
这是一个示例模块

这个模块演示了如何编写文档字符串
"""

def add(a, b):
    """计算两个数的和"""
    return a + b

函数文档字符串

def calculate_area(radius):
    """
    计算圆的面积

    参数:
        radius (float): 圆的半径

    返回:
        float: 圆的面积

    示例:
        >>> calculate_area(5)
        78.53981633974483
    """
    import math
    return math.pi * radius ** 2

类文档字符串

class Rectangle:
    """
    矩形类

    属性:
        width (float): 矩形的宽度
        height (float): 矩形的高度

    方法:
        area(): 计算面积
        perimeter(): 计算周长
    """

    def __init__(self, width, height):
        """初始化矩形"""
        self.width = width
        self.height = height

    def area(self):
        """计算矩形面积"""
        return self.width * self.height

注释的最佳实践

1. 解释"为什么"而不是"是什么"

# 好的注释
# 使用快速排序算法，因为时间复杂度为 O(n log n)
def sort_array(arr):
    pass

# 不好的注释
# 对数组进行排序
def sort_array(arr):
    pass

2. 保持注释简洁明了

# 好的注释
# 计算圆的面积
area = math.pi * radius ** 2

# 不好的注释
# 这里我们使用数学库中的 pi 常量，然后乘以半径的平方来计算圆的面积
area = math.pi * radius ** 2

3. 及时更新注释

# 好的做法：代码和注释保持同步
# 计算矩形面积（包括长和宽）
area = length * width

# 不好的做法：注释过时
# 计算正方形面积
area = length * width

4. 避免无用的注释

# 不好的注释
i = i + 1  # i 加 1

# 好的做法：直接写代码
i = i + 1

5. 使用注释标记待办事项

# TODO: 添加错误处理
def process_data(data):
    result = data * 2
    return result

# FIXME: 这个算法效率不高，需要优化
def slow_function():
    pass

# HACK: 临时解决方案，需要重构
def temp_solution():
    pass

注释的位置

行尾注释

x = 10  # 初始化变量
y = 20  # 另一个变量

独立行注释

# 初始化变量
x = 10
y = 20

代码块前注释

# 计算圆的面积和周长
import math

radius = 5
area = math.pi * radius ** 2
circumference = 2 * math.pi * radius

print(f"面积: {area}")
print(f"周长: {circumference}")

注释的用途

1. 解释复杂逻辑

# 使用欧几里得算法计算最大公约数
def gcd(a, b):
    while b:
        a, b = b, a % b
    return a

2. 说明算法选择

# 使用二分查找，因为数组已排序，时间复杂度为 O(log n)
def binary_search(arr, target):
    left, right = 0, len(arr) - 1
    while left <= right:
        mid = (left + right) // 2
        if arr[mid] == target:
            return mid
        elif arr[mid] < target:
            left = mid + 1
        else:
            right = mid - 1
    return -1

3. 标记已知问题

# 注意：这个函数在处理空列表时可能会出错
def process_list(items):
    for item in items:
        print(item)

4. 提供使用示例

def calculate_discount(price, discount_rate):
    """
    计算折扣后的价格

    参数:
        price (float): 原价
        discount_rate (float): 折扣率（0-1之间）

    返回:
        float: 折扣后的价格

    示例:
        >>> calculate_discount(100, 0.2)
        80.0
    """
    return price * (1 - discount_rate)

禁用代码

使用注释临时禁用代码：

# print("这段代码被禁用了")
# print("暂时不需要执行")

# 备选方案
print("使用新的实现")

访问文档字符串

使用 help() 函数或 __doc__ 属性访问文档字符串：

def add(a, b):
    """计算两个数的和"""
    return a + b

# 使用 help()
help(add)

# 使用 __doc__
print(add.__doc__)

注释风格指南

PEP 8 建议

• 注释应该完整、清晰
• 注释应该与代码保持同步
• 避免使用无意义的注释
• 使用英文或中文保持一致性

总结

注释是代码的重要组成部分：

• 单行注释：使用 # 符号
• 多行注释：使用多个 # 或三引号
• 文档字符串：描述模块、函数、类
• 最佳实践：解释"为什么"而不是"是什么"
• 保持同步：及时更新注释

良好的注释习惯可以提高代码质量，使代码更易于理解和维护。