第16课：注释小助手——养成好习惯
🎯 本课目标
- 理解注释的作用和重要性
- 掌握单行注释和多行注释的写法
- 学会编写有意义的注释
- 了解文档字符串的使用
- 养成编写注释的好习惯
📝 趣味引入：代码的"翻译官"
想象一下：你的代码就像一本外文书：
- 🔤 计算机能直接"读懂"代码
- 👥 但其他人（包括未来的你）可能看不懂
- 💡 注释就是代码的"翻译"，解释代码的意思
- 🎯 好的注释让代码更容易理解和维护
今天，让我们学习如何成为优秀的代码"翻译官"，用注释让代码更清晰！
🔧 第一部分：认识注释
1.1 注释是什么？
# 注释是写给人类看的说明文字
# Python解释器会忽略注释
# 注释以#号开头，直到行尾
print("你好，世界！") # 这是一个简单的打印语句
# 上面的代码会显示"你好，世界！"
# 注释不会影响程序的运行
# 但能让代码更容易理解1.2 为什么需要注释？
# 示例1：没有注释的代码（难以理解）
x = 10
y = 5
z = x + y
print(z)
# 示例2：有注释的代码（容易理解）
# 计算两个数的和
num1 = 10 # 第一个数
num2 = 5 # 第二个数
total = num1 + num2 # 计算总和
print(f"两数之和是：{total}") # 输出结果
# 对比一下，哪个更容易理解？📋 第二部分：注释的类型
2.1 单行注释
# 单行注释示例
# ==============================
# 1. 在代码行上方写注释
# 这是一个问候程序
name = "小明"
print(f"你好，{name}！")
# 2. 在代码行后面写注释
age = 12 # 设置年龄为12岁
height = 1.52 # 设置身高为1.52米
# 3. 多行单行注释
# 程序名称：学生信息管理
# 作者：小明
# 创建时间：2023年10月
# 功能：管理学生基本信息
# 4. 用注释暂时禁用代码（调试）
# print("这行代码暂时不执行")
print("这行代码会执行")
# 5. 用注释分隔代码块
# ==============================
# 计算部分
# ==============================
score1 = 85
score2 = 92
average = (score1 + score2) / 22.2 多行注释
# 多行注释示例
# ==============================
# 方法1：使用多个#号
# 这是一个多行注释的例子
# 每行都以#号开头
# 这样可以写很长的说明
# 方法2：使用三引号（推荐用于长注释）
"""
程序名称：学生成绩计算器
功能：计算学生的总分和平均分
作者：小明
版本：1.0
使用说明：
1. 输入各科成绩
2. 程序会自动计算
3. 显示结果
"""
# 方法3：使用三单引号
'''
这是一个多行注释
可以写很多行
Python会忽略这些内容
'''
# 实际示例：计算圆的面积
"""
计算圆的面积
公式：面积 = π × 半径²
参数：
radius: 圆的半径
返回值：圆的面积
"""
import math
radius = 5
area = math.pi * radius ** 2
print(f"半径为{radius}的圆的面积是：{area:.2f}")🎯 第三部分：如何写好的注释
3.1 好的注释示例
# 好的注释示例
# ==============================
# 示例1：解释复杂逻辑
# 判断学生成绩等级
# 90分以上：优秀
# 80-89分：良好
# 70-79分：中等
# 60-69分：及格
# 60分以下：不及格
score = 85
if score >= 90:
grade = "优秀"
elif score >= 80:
grade = "良好"
elif score >= 70:
grade = "中等"
elif score >= 60:
grade = "及格"
else:
grade = "不及格"
print(f"成绩：{score}分，等级：{grade}")
# 示例2：解释为什么要这样做
# 将字符串转换为整数，因为用户输入的是字符串
# 需要转换为整数才能进行数学计算
user_input = "25" # 用户输入的年龄
age = int(user_input) # 转换为整数
next_year_age = age + 1
print(f"明年你就{next_year_age}岁了")
# 示例3：标记待办事项
# TODO: 添加异常处理
# TODO: 优化计算速度
# FIXME: 这里的逻辑需要检查
# NOTE: 重要提示3.2 不好的注释示例
# 不好的注释示例
# ==============================
# 示例1：注释太明显（多余）
x = 5 # 把5赋值给x
print(x) # 打印x
# 更好的写法：
score = 5 # 设置分数
print(score) # 显示分数
# 示例2：注释过时（与实际代码不符）
# 计算两个数的差
result = 10 + 5 # 注释说是计算差，但代码是计算和
# 正确的写法：
# 计算两个数的和
result = 10 + 5
# 示例3：注释没有提供有用信息
# 做了一些计算
a = 10
b = 20
c = a + b
# 更好的写法：
# 计算商品总价
price = 10 # 单价
quantity = 20 # 数量
total = price * quantity # 总价3.3 注释练习：找出问题
# 注释练习：找出注释中的问题
print("🔍 注释找错练习")
print("=" * 40)
# 有问题的代码示例
examples = [
'''
# 计算
x = 5
y = 3
z = x + y
''',
'''
# 打印一些东西
# 这是一行代码
print("Hello")
''',
'''
# 计算两个数的和（这是昨天的代码）
result = 10 - 5
''',
'''
# a是年龄，b是身高
age = 12
height = 1.5
# 计算BMI
weight = 40
bmi = weight / (height * height)
'''
]
print("找出以下代码中注释的问题：")
for i, code in enumerate(examples, 1):
print(f"\n{i}. 代码：")
print(code)
input("按回车查看分析...")
if i == 1:
print(" 问题：注释太简单，没有说明计算的是什么")
print(" 建议：改为 '# 计算两个数的和'")
elif i == 2:
print(" 问题：注释没有提供有用信息")
print(" 建议：说明打印的目的")
elif i == 3:
print(" 问题：注释与代码不符")
print(" 建议：更新注释或修正代码")
elif i == 4:
print(" 问题：变量名与注释不符")
print(" 建议：注释中的a、b应该用变量名")📖 第四部分：文档字符串
4.1 什么是文档字符串？
# 文档字符串示例
# ==============================
def calculate_bmi(weight, height):
"""
计算身体质量指数（BMI）
参数：
weight: 体重（公斤）
height: 身高（米）
返回值：
BMI值（浮点数）
公式：
BMI = 体重 / (身高²)
"""
bmi = weight / (height ** 2)
return bmi
# 使用函数
my_weight = 45
my_height = 1.55
my_bmi = calculate_bmi(my_weight, my_height)
print(f"你的BMI是：{my_bmi:.1f}")
# 查看文档字符串
print("\n📖 函数文档：")
print(calculate_bmi.__doc__)4.2 文档字符串的实际应用
# 学生信息管理函数
def add_student(name, age, grade):
"""
添加一个学生到系统
参数：
name: 学生姓名（字符串）
age: 学生年龄（整数）
grade: 学生年级（字符串）
返回值：
学生信息字典
示例：
>>> student = add_student("小明", 12, "五年级")
>>> print(student["name"])
小明
"""
student = {
"name": name,
"age": age,
"grade": grade
}
return student
def calculate_average(scores):
"""
计算平均分
参数：
scores: 成绩列表（列表）
返回值：
平均分（浮点数）
异常：
如果列表为空，返回0.0
"""
if not scores: # 如果列表为空
return 0.0
total = sum(scores)
average = total / len(scores)
return average
# 使用示例
print("🎒 学生信息管理示例")
print("=" * 40)
# 添加学生
student1 = add_student("张小红", 11, "四年级")
print(f"添加学生：{student1}")
# 计算平均分
scores = [85, 92, 78, 90, 88]
avg = calculate_average(scores)
print(f"平均分：{avg:.1f}")
# 显示函数文档
print("\n📋 函数说明：")
print("1. add_student 函数：")
print(add_student.__doc__[:200] + "...") # 显示前200个字符🎮 第五部分：注释游戏
游戏1：注释填空
# 注释填空游戏
print("🎯 注释填空游戏")
print("=" * 40)
print("请为下面的代码添加合适的注释")
# 题目1：计算矩形面积
code1 = '''
# TODO: 添加函数说明
def calculate_area(length, width):
# TODO: 添加参数说明
# TODO: 添加返回值说明
area = length * width
return area
'''
print("\n1. 矩形面积计算函数：")
print(code1)
input("\n按回车查看参考答案...")
answer1 = '''
"""
计算矩形的面积
参数：
length: 矩形的长度
width: 矩形的宽度
返回值：
矩形的面积
"""
def calculate_area(length, width):
# 计算面积：长 × 宽
area = length * width
return area
'''
print("参考答案：")
print(answer1)
# 题目2：判断闰年
print("\n" + "=" * 40)
code2 = '''
# TODO: 添加函数说明
def is_leap_year(year):
# TODO: 添加闰年判断逻辑的注释
if year % 400 == 0:
return True
elif year % 100 == 0:
return False
elif year % 4 == 0:
return True
else:
return False
'''
print("\n2. 闰年判断函数：")
print(code2)
input("\n按回车查看参考答案...")
answer2 = '''
"""
判断是否是闰年
规则：
1. 能被400整除的是闰年
2. 能被100整除但不是400整除的不是闰年
3. 能被4整除但不是100整除的是闰年
4. 其他不是闰年
参数：
year: 年份
返回值：
如果是闰年返回True，否则返回False
"""
def is_leap_year(year):
# 能被400整除的是闰年
if year % 400 == 0:
return True
# 能被100整除但不是400整除的不是闰年
elif year % 100 == 0:
return False
# 能被4整除但不是100整除的是闰年
elif year % 4 == 0:
return True
# 其他情况不是闰年
else:
return False
'''
print("参考答案：")
print(answer2)游戏2：代码理解挑战
# 代码理解挑战
print("🔍 代码理解挑战")
print("=" * 40)
print("阅读代码，回答问题")
# 有注释的代码
code_with_comments = '''
# 学生成绩管理系统
# 版本：1.0
# 作者：编程小助手
def calculate_grade(score):
"""
根据分数判断等级
等级标准：
A: 90-100分
B: 80-89分
C: 70-79分
D: 60-69分
F: 0-59分
参数：
score: 分数（0-100）
返回值：
等级（字符串）
"""
if score >= 90:
return "A"
elif score >= 80:
return "B"
elif score >= 70:
return "C"
elif score >= 60:
return "D"
else:
return "F"
def analyze_scores(scores):
"""
分析成绩列表
参数：
scores: 成绩列表
返回值：
分析结果字典
"""
if not scores: # 如果列表为空
return {"error": "没有成绩数据"}
# 计算统计信息
highest = max(scores) # 最高分
lowest = min(scores) # 最低分
average = sum(scores) / len(scores) # 平均分
# 统计各等级人数
grade_counts = {"A": 0, "B": 0, "C": 0, "D": 0, "F": 0}
for score in scores:
grade = calculate_grade(score)
grade_counts[grade] += 1
return {
"最高分": highest,
"最低分": lowest,
"平均分": average,
"等级分布": grade_counts
}
'''
print("有注释的代码：")
print(code_with_comments)
# 没有注释的代码
code_without_comments = '''
def cg(s):
if s >= 90:
return "A"
elif s >= 80:
return "B"
elif s >= 70:
return "C"
elif s >= 60:
return "D"
else:
return "F"
def as(sl):
if not sl:
return {"e": "没有数据"}
h = max(sl)
l = min(sl)
a = sum(sl) / len(sl)
gc = {"A": 0, "B": 0, "C": 0, "D": 0, "F": 0}
for s in sl:
g = cg(s)
gc[g] += 1
return {
"h": h,
"l": l,
"a": a,
"gc": gc
}
'''
print("\n" + "=" * 40)
print("没有注释的代码：")
print(code_without_comments)
# 问题
print("\n" + "=" * 40)
print("❓ 问题：")
print("1. 哪个代码更容易理解？")
print("2. 第二个代码中'cg'函数的作用是什么？")
print("3. 第二个代码中'as'函数返回的字典包含哪些信息？")
input("\n按回车查看答案...")
print("\n✅ 答案：")
print("1. 第一个有注释的代码更容易理解")
print("2. 'cg'函数是根据分数判断等级")
print("3. 包含：最高分(h)、最低分(l)、平均分(a)、等级分布(gc)")
print("\n💡 结论：好的注释让代码更容易理解！")📁 第六部分：实际项目应用
项目1：带注释的名片生成器
"""
名片生成器 - 第10课项目优化版
功能：生成个性化的电子名片
作者：编程小学员
版本：2.0
添加了完整的注释
"""
import datetime
import random
def get_personal_info():
"""
收集用户的个人信息
返回值：
包含用户信息的字典
"""
print("\n📝 请填写个人信息：")
print("-" * 30)
# 创建信息字典
info = {}
# 获取姓名
info['name'] = input("姓名：")
# 获取昵称
info['nickname'] = input("昵称（小名）：")
# 获取年龄（带验证）
while True:
try:
age = int(input("年龄："))
if 1 <= age <= 20: # 年龄范围验证
info['age'] = age
break
else:
print("⚠️ 请输入1-20之间的年龄")
except ValueError: # 处理非数字输入
print("❌ 请输入数字！")
# 获取学校信息
info['school'] = input("学校：")
info['class'] = input("班级：")
# 获取联系方式（可选）
info['phone'] = input("电话（可选）：")
info['email'] = input("邮箱（可选）：")
# 获取个人描述
info['hobby'] = input("爱好：")
info['favorite_subject'] = input("最喜欢的科目：")
info['dream'] = input("你的梦想：")
return info
def generate_card_id():
"""
生成唯一的卡片ID
ID格式：CARD-月日-随机数
例如：CARD-1015-123
返回值：
卡片ID（字符串）
"""
# 获取当前日期
now = datetime.datetime.now()
# 格式化为月日
date_str = now.strftime("%m%d")
# 生成3位随机数
random_num = random.randint(100, 999)
# 组合成ID
card_id = f"CARD-{date_str}-{random_num}"
return card_id
def create_simple_card(info):
"""
创建简洁风格的名片
参数：
info: 用户信息字典
返回值：
名片字典
"""
# 生成卡片ID
card_id = generate_card_id()
# 获取当前时间
create_time = datetime.datetime.now().strftime("%Y-%m-%d %H:%M")
# 打印名片
print("\n" + "=" * 50)
print(" 📇 个人名片 - 简洁版")
print("=" * 50)
# 显示基本信息
print(f"名片ID：{card_id}")
print(f"制作时间：{create_time}")
print() # 空行
# 显示个人信息
print(f"👤 姓名：{info['name']}")
if info['nickname']: # 如果有昵称才显示
print(f"🏷️ 昵称：{info['nickname']}")
print(f"🎂 年龄：{info['age']}岁")
print(f"🏫 学校：{info['school']}")
print(f"📚 班级：{info['class']}")
# 显示联系方式（如果有）
if info['phone']:
print(f"📱 电话：{info['phone']}")
if info['email']:
print(f"📧 邮箱：{info['email']}")
# 显示个人描述
print(f"🎯 爱好：{info['hobby']}")
print(f"📖 最喜欢科目：{info['favorite_subject']}")
print(f"✨ 梦想：{info['dream']}")
print("=" * 50)
# 返回名片数据
return {
'id': card_id,
'info': info,
'time': create_time
}
def save_card_to_file(card, style="简洁风格"):
"""
将名片保存到文本文件
参数：
card: 名片字典
style: 名片风格
返回值：
成功返回True，失败返回False
"""
# 检查是否有名片数据
if not card:
print("❌ 没有可保存的名片")
return False
# 获取信息
info = card['info']
# 生成文件名：姓名_风格_名片.txt
filename = f"{info['name']}_{style}_名片.txt"
try:
# 打开文件进行写入
with open(filename, 'w', encoding='utf-8') as f:
# 写入文件头
f.write("=" * 50 + "\n")
f.write(" 个人名片文件\n")
f.write("=" * 50 + "\n\n")
# 写入基本信息
f.write(f"名片ID：{card.get('id', '未知')}\n")
f.write(f"制作时间：{card.get('time', '未知')}\n")
f.write(f"名片风格：{style}\n\n")
# 写入个人信息
f.write("【基本信息】\n")
f.write(f"姓名：{info['name']}\n")
if info.get('nickname'):
f.write(f"昵称：{info['nickname']}\n")
f.write(f"年龄：{info['age']}岁\n")
f.write(f"学校：{info['school']}\n")
f.write(f"班级：{info['class']}\n\n")
# 写入联系方式
f.write("【联系信息】\n")
if info.get('phone'):
f.write(f"电话：{info['phone']}\n")
if info.get('email'):
f.write(f"邮箱：{info['email']}\n\n")
# 写入个人描述
f.write("【个人描述】\n")
f.write(f"爱好：{info['hobby']}\n")
f.write(f"最喜欢科目：{info['favorite_subject']}\n")
f.write(f"梦想：{info['dream']}\n")
# 文件尾
f.write("\n" + "=" * 50 + "\n")
# 成功提示
print(f"✅ 名片已保存到：{filename}")
return True
except Exception as e: # 捕获所有异常
# 失败提示
print(f"❌ 保存失败：{e}")
return False
def main():
"""
主函数 - 程序入口点
控制程序的主要流程：
1. 显示欢迎信息
2. 收集用户信息
3. 生成名片
4. 询问是否保存
5. 退出程序
"""
# 程序标题
print("🎫" * 15)
print(" 智能名片生成系统 v2.0")
print("🎫" * 15)
print("\n欢迎使用智能名片生成系统！")
# 收集个人信息
info = get_personal_info()
# 主循环
while True:
# 显示菜单
print("\n" + "=" * 30)
print("请选择名片风格：")
print("1. 🎨 简洁风格")
print("2. ✨ 花式风格")
print("3. 🎒 学生风格")
print("4. 🔄 重新填写信息")
print("5. 🚪 退出系统")
print("=" * 30)
# 获取用户选择
choice = input("\n你的选择（1-5）：")
# 处理选择
if choice == "1":
# 创建简洁风格名片
card = create_simple_card(info)
# 询问是否保存
save = input("\n是否保存到文件？（是/否）：")
if save.lower() in ['是', 'yes', 'y']:
save_card_to_file(card, "简洁风格")
elif choice == "2":
# TODO: 实现花式风格
print("\n✨ 花式风格功能开发中...")
elif choice == "3":
# TODO: 实现学生风格
print("\n🎒 学生风格功能开发中...")
elif choice == "4":
# 重新填写信息
print("\n重新填写信息：")
info = get_personal_info()
elif choice == "5":
# 退出程序
print("\n🎉 感谢使用名片生成系统！")
print("再见！👋")
break
else:
# 无效选择
print("❌ 请选择1-5的数字！")
# 暂停，让用户看到结果
input("\n按回车键继续...")
# 程序入口
if __name__ == "__main__":
"""
这是程序的入口点
当直接运行这个文件时，会从这里开始执行
"""
main()项目2：带注释的计算器
"""
简单计算器程序
功能：进行基本的数学运算
支持：加、减、乘、除、取余、幂运算
作者：编程学习者
版本：1.0
"""
def add(a, b):
"""
加法运算
参数：
a: 第一个数
b: 第二个数
返回值：
两数之和
"""
return a + b
def subtract(a, b):
"""减法运算"""
return a - b
def multiply(a, b):
"""乘法运算"""
return a * b
def divide(a, b):
"""
除法运算
参数：
a: 被除数
b: 除数
返回值：
商（浮点数）
异常：
如果除数为0，返回错误信息
"""
if b == 0:
return "错误：除数不能为0！"
return a / b
def modulo(a, b):
"""取余运算"""
if b == 0:
return "错误：除数不能为0！"
return a % b
def power(a, b):
"""幂运算（a的b次方）"""
return a ** b
def get_number_input(prompt):
"""
获取用户输入的数字
参数：
prompt: 提示信息
返回值：
用户输入的数字（浮点数）
说明：
会一直提示用户，直到输入有效的数字
"""
while True:
try:
# 获取用户输入
user_input = input(prompt)
# 尝试转换为浮点数
number = float(user_input)
return number
except ValueError:
# 如果转换失败，提示重新输入
print("❌ 请输入有效的数字！")
def show_menu():
"""
显示计算器菜单
返回值：
用户选择的操作编号
"""
print("\n" + "=" * 40)
print("🧮 简单计算器")
print("=" * 40)
print("请选择运算：")
print("1. 加法 (+)")
print("2. 减法 (-)")
print("3. 乘法 (×)")
print("4. 除法 (÷)")
print("5. 取余 (%)")
print("6. 幂运算 (^)")
print("7. 退出")
print("=" * 40)
# 获取用户选择
choice = input("请选择 (1-7): ")
return choice
def main():
"""
计算器主程序
流程：
1. 显示菜单
2. 获取用户选择
3. 获取操作数
4. 执行计算
5. 显示结果
6. 重复直到退出
"""
print("欢迎使用简单计算器！")
while True:
# 显示菜单
choice = show_menu()
# 处理退出
if choice == "7":
print("\n感谢使用计算器，再见！👋")
break
# 检查选择是否有效
if choice not in ["1", "2", "3", "4", "5", "6"]:
print("❌ 请选择1-7的数字！")
continue
# 获取操作数
print("\n请输入操作数：")
num1 = get_number_input("第一个数: ")
num2 = get_number_input("第二个数: ")
# 根据选择执行相应的运算
if choice == "1": # 加法
result = add(num1, num2)
symbol = "+"
elif choice == "2": # 减法
result = subtract(num1, num2)
symbol = "-"
elif choice == "3": # 乘法
result = multiply(num1, num2)
symbol = "×"
elif choice == "4": # 除法
result = divide(num1, num2)
symbol = "÷"
elif choice == "5": # 取余
result = modulo(num1, num2)
symbol = "%"
elif choice == "6": # 幂运算
result = power(num1, num2)
symbol = "^"
# 显示结果
print(f"\n📊 计算结果：")
print(f" {num1} {symbol} {num2} = {result}")
# 暂停，让用户看到结果
input("\n按回车键继续...")
# 程序入口
if __name__ == "__main__":
main()项目3：注释检查工具
"""
注释检查工具
功能：检查Python文件中的注释情况
帮助：养成写注释的好习惯
"""
import os
def check_file_comments(filename):
"""
检查Python文件的注释情况
参数：
filename: 要检查的文件名
返回值：
检查结果字典
"""
# 初始化统计
stats = {
'total_lines': 0, # 总行数
'code_lines': 0, # 代码行数
'comment_lines': 0, # 注释行数
'empty_lines': 0, # 空行数
'has_docstring': False, # 是否有文档字符串
'comment_ratio': 0.0, # 注释比例
'suggestions': [] # 改进建议
}
try:
# 打开文件
with open(filename, 'r', encoding='utf-8') as f:
lines = f.readlines()
# 统计行数
stats['total_lines'] = len(lines)
in_multiline_comment = False
for i, line in enumerate(lines, 1):
# 去除两端的空白字符
stripped_line = line.strip()
# 跳过空行
if not stripped_line:
stats['empty_lines'] += 1
continue
# 检查是否是注释
if stripped_line.startswith('#'):
stats['comment_lines'] += 1
elif stripped_line.startswith('"""') or stripped_line.startswith("'''"):
if in_multiline_comment:
in_multiline_comment = False
else:
in_multiline_comment = True
stats['has_docstring'] = True
else:
# 如果不是注释也不是空行，就是代码行
if not in_multiline_comment:
stats['code_lines'] += 1
# 计算注释比例
if stats['code_lines'] > 0:
stats['comment_ratio'] = stats['comment_lines'] / stats['code_lines']
# 生成建议
if stats['comment_ratio'] < 0.1: # 注释比例低于10%
stats['suggestions'].append("💡 注释太少，建议增加注释")
if not stats['has_docstring']:
stats['suggestions'].append("💡 建议添加文档字符串")
if stats['comment_lines'] == 0:
stats['suggestions'].append("⚠️ 没有找到任何注释！")
return stats
except FileNotFoundError:
print(f"❌ 文件不存在：{filename}")
return None
except Exception as e:
print(f"❌ 读取文件出错：{e}")
return None
def analyze_my_code():
"""
分析自己的代码文件
"""
print("🔍 注释检查工具")
print("=" * 50)
# 获取当前目录下的Python文件
python_files = []
for file in os.listdir('.'):
if file.endswith('.py'):
python_files.append(file)
if not python_files:
print("没有找到Python文件")
return
print("找到以下Python文件：")
for i, file in enumerate(python_files, 1):
print(f"{i}. {file}")
# 让用户选择文件
try:
choice = int(input(f"\n选择要检查的文件 (1-{len(python_files)}): "))
if 1 <= choice <= len(python_files):
filename = python_files[choice-1]
print(f"\n正在检查文件：{filename}")
print("-" * 50)
# 检查文件
result = check_file_comments(filename)
if result:
# 显示结果
print("📊 检查结果：")
print(f" 总行数：{result['total_lines']}")
print(f" 代码行：{result['code_lines']}")
print(f" 注释行：{result['comment_lines']}")
print(f" 空行数：{result['empty_lines']}")
print(f" 注释比例：{result['comment_ratio']:.1%}")
if result['has_docstring']:
print(" 文档字符串：✅ 有")
else:
print(" 文档字符串：❌ 无")
# 显示建议
if result['suggestions']:
print("\n💡 改进建议：")
for suggestion in result['suggestions']:
print(f" {suggestion}")
else:
print("\n✅ 注释情况良好！")
else:
print("❌ 选择无效！")
except ValueError:
print("❌ 请输入数字！")
# 运行检查工具
if __name__ == "__main__":
analyze_my_code()📅 下节课预告
第17课：交互式故事书——制作分支故事
下节课你将学习：
- 使用条件语句创建分支故事
- 根据用户选择展示不同情节
- 制作有趣的互动故事
- 管理复杂的故事线
- 添加故事选项和结局
预习思考：
- 如何让程序根据用户选择做出不同反应？
- 如何设计有趣的故事情节？
- 如何管理多个故事分支？
💬 给家长的话
亲爱的家长：
今天孩子学习了编程中非常重要的好习惯——写注释。注释是代码的"说明书"，能让代码更容易理解和维护。
孩子今天学会了：
- ✅ 单行注释和多行注释的写法
- ✅ 如何编写有意义的注释
- ✅ 文档字符串的使用
- ✅ 识别好的注释和不好的注释
- ✅ 养成写注释的好习惯
注释的重要性：
| 注释类型 | 用途 | 重要性 | 习惯培养 |
|---------|------|--------|---------|
| 单行注释 | 解释一行代码 | 理解具体实现 | 细节关注 |
| 多行注释 | 解释代码块 | 理解整体逻辑 | 整体思维 |
| 文档字符串 | 说明函数用途 | 接口文档 | 规范意识 |
| TODO注释 | 标记待办事项 | 任务管理 | 规划能力 |
您可以这样做：
习惯培养：
- 代码审查：和孩子一起阅读带注释的代码
- 注释练习：让孩子为已有的代码添加注释
- 文档阅读：一起阅读Python官方文档
- 习惯打卡：鼓励孩子为每个程序都写注释
思维训练：
- 讨论：为什么要写注释？写给谁看？
- 思考：什么样的注释是有帮助的？
- 比较：有注释和没注释的代码区别
- 实践：检查自己以前代码的注释情况
温馨提示：
- 写注释是好习惯，越早养成越好
- 注释要简洁明了，不要过度注释
- 鼓励孩子既写代码也写注释
- 注释应该解释"为什么"，而不是"是什么"
🏆 今日成就
完成了今天的学习，你：
📝 理解了注释的重要性
💡 学会了写有意义的注释
📖 掌握了文档字符串
🔍 能识别注释好坏
✅ 养成了注释习惯
挑战任务：
- 为之前写的所有程序添加注释
- 创建一个带完整注释的新程序
- 检查并改进现有代码的注释
- 制作代码注释规范手册
🌟 编程心法
代码是写给计算机的指令
注释是写给人类的说明
好的注释
是给未来自己的信
是给合作者的地图
是给使用者的指南
从今天起
让每行重要代码都有注释
让每个函数都有文档
让习惯成为自然
让代码因注释而清晰记住：优秀的程序员不仅会写能运行的代码，还会写让人能看懂的代码。注释就是你看懂代码的桥梁！
第16课结束。你现在已经养成了写注释的好习惯！
实践任务：
1. 为所有旧程序添加注释
2. 创建带完整注释的新项目
3. 检查改进代码注释
4. 制定个人注释规范
下节课，让我们创作交互式故事，让程序更有趣！
第17课见！📖