本文目录导读：
在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
- 清晰简洁 - 注释要简短明了
- 解释目的 - 说明代码的目的，而不是重复代码
- 及时更新 - 修改代码时同步更新注释
- 合理使用 - 不是所有代码都需要注释
- 使用中文 - 国内团队建议使用中文注释
好的代码自解释,好的注释解释为什么这样做。
