Python案例如何加注释说明

本文目录导读：

1. 单行注释（#）
2. 多行注释（三引号）
3. 函数注释（文档字符串）
4. 完整案例展示
5. 注释的最佳实践
6. 使用类型注解（Python 3.5+）

在Python案例中添加注释是非常重要的编程习惯,能帮助自己和他人理解代码，以下是几种常见的注释方法和实际案例：

单行注释（#）

使用井号 进行单行注释：

# 计算圆的面积
radius = 5  # 半径值
area = 3.14159 * radius ** 2  # 面积公式：π * r²
print(f"圆的面积是：{area}")  # 输出结果

多行注释（三引号）

使用三个单引号或双引号：

"""
这是一个计算圆面积的程序
作者：小明
日期：2024-01-15
功能：根据半径计算圆的面积
"""
radius = 5
area = 3.14159 * radius ** 2
print(f"圆的面积是：{area}")

函数注释（文档字符串）

在函数内部第一行使用三引号：

def calculate_area(radius):
    """
    计算圆的面积
    参数:
        radius (float): 圆的半径
    返回:
        float: 圆的面积
    """
    return 3.14159 * radius ** 2
# 使用函数
result = calculate_area(5)
print(f"面积为：{result}")

完整案例展示

这里是一个更完整的数据分析案例：

"""
学生成绩分析程序
功能：读取学生成绩，计算统计信息
"""
# 导入需要的库
import statistics
def analyze_scores(scores):
    """
    分析学生成绩的统计信息
    参数:
        scores (list): 学生成绩列表
    返回:
        dict: 包含平均值、中位数、最高分、最低分的字典
    """
    # 计算平均值
    average = sum(scores) / len(scores)
    # 计算中位数
    median = statistics.median(scores)
    # 找出最高分和最低分
    max_score = max(scores)  # 最高分
    min_score = min(scores)  # 最低分
    # 返回统计结果
    return {
        "平均分": round(average, 2),  # 四舍五入保留2位小数
        "中位数": median,
        "最高分": max_score,
        "最低分": min_score
    }
# 主程序
if __name__ == "__main__":
    # 学生成绩数据
    student_scores = [85, 92, 78, 95, 88, 76, 90]
    # 调用分析函数
    result = analyze_scores(student_scores)
    # 输出结果
    print("=== 成绩分析结果 ===")
    for key, value in result.items():
        print(f"{key}: {value}")

注释的最佳实践

# 1. 解释"为什么"而不是"是什么"
# 错误：循环10次
# 正确：需要测试10个不同温度条件下的反应速度
for i in range(10):
    test_temperature(i)
# 2. 为复杂算法添加注释
def fibonacci(n):
    """使用动态规划计算斐波那契数列第n项"""
    if n <= 1:
        return n
    # 创建dp数组存储中间结果
    dp = [0] * (n + 1)
    dp[1] = 1
    # 自底向上计算
    for i in range(2, n + 1):
        dp[i] = dp[i-1] + dp[i-2]
    return dp[n]
# 3. 标记待办事项
def process_data(data):
    # TODO: 需要优化这个函数，当前性能较慢
    # FIXME: 处理边界情况时可能出错
    pass

使用类型注解（Python 3.5+）

def add_numbers(a: int, b: int) -> int:
    """计算两个整数的和
    参数:
        a: 第一个加数
        b: 第二个加数
    返回:
        两个数的和
    """
    return a + b

1. 清晰简洁 - 注释要简短明了
2. 解释目的 - 说明代码的目的，而不是重复代码
3. 及时更新 - 修改代码时同步更新注释
4. 合理使用 - 不是所有代码都需要注释
5. 使用中文 - 国内团队建议使用中文注释

好的代码自解释,好的注释解释为什么这样做。