003 注释

以下是一份关于 Python 语言注释的详细教案，包含教学目标、内容、示例、练习与作业设计，可直接用于课堂教学：

---

教案：Python 语言注释

教学目标

1. 理解注释的作用及重要性。
2. 掌握单行注释、多行注释的语法。
3. 学会使用文档字符串（Docstring）编写函数/模块说明。
4. 能在实际代码中合理添加注释。

---

教学重点与难点

• 重点：单行注释与多行注释的语法规则。
• 难点：区分注释与字符串，以及文档字符串的规范写法。

---

课堂内容与示例

1. 注释的作用

• 为什么需要注释？
  • 解释代码功能，提高可读性。
  • 调试时临时禁用代码。
  • 为团队协作提供说明（如函数用途、参数含义）。

2. 单行注释

• 语法：以 # 开头，后方内容为注释。
• 示例：

  # 计算圆的面积（单行注释）
  radius = 5
  area = 3.14 * radius ** 2  # 这里是行尾注释
  

3. 多行注释

• 语法：使用三引号 ''' 或 """ 包裹注释内容（本质是字符串，但未赋值时被解释器忽略）。
• 示例：

  '''
  这是一个多行注释
  用于说明以下代码的功能：
  1. 获取用户输入
  2. 转换为整数
  '''
  user_input = input("请输入数字：")
  number = int(user_input)
  

4. 文档字符串（Docstring）

• 用途：为函数、类、模块提供官方说明，可通过 help() 查看。
• 语法：写在函数/类定义的首行，用三引号包裹。
• 示例：

  def add(a, b):
      """
      计算两个数的和
      
      参数:
          a (int/float): 第一个数字
          b (int/float): 第二个数字
          
      返回:
          int/float: a 与 b 的和
      """
      return a + b
  
  # 查看文档字符串
  help(add)  # 或 print(add.__doc__)
  

---

课堂练习

练习1：添加注释

修改以下代码，添加单行注释和多行注释：

price = 100
discount = 0.8
final_price = price * discount
print(final_price)

参考答案：

# 商品原价
price = 100  
# 折扣率
discount = 0.8  

'''
计算最终价格并输出：
1. 原价乘以折扣率
2. 打印结果
'''
final_price = price * discount  
print("最终价格：", final_price)

练习2：注释调试

将以下代码块通过注释临时禁用：

print("这行代码暂时不需要执行")
x = 10 + 20

参考答案：

# print("这行代码暂时不需要执行")
# x = 10 + 20

---

课后作业

作业1：编写带注释的函数

编写一个函数 is_even(num)，判断数字是否为偶数，并添加文档字符串说明。

参考答案：

def is_even(num):
    """
    判断一个数字是否为偶数
    
    参数:
        num (int): 待判断的整数
        
    返回:
        bool: 如果是偶数返回 True，否则返回 False
    """
    return num % 2 == 0

作业2：注释规范检查

提供一段无注释的代码，要求学生补充合理注释（示例代码）：

def celsius_to_fahrenheit(c):
    f = c * 9/5 + 32
    return f

---

注意事项

1. 注释与代码的缩进需一致。
2. 避免无意义的注释（如 x = 5 # 将5赋值给x）。
3. 多行注释避免嵌套使用三引号（如 '''注释1 '''注释2''' ''' 会报错）。

---

教学总结

• 注释是代码的说明书：清晰的注释能提升代码可维护性。
• 适度注释：无需过度注释，重点解释复杂逻辑或关键参数。

---

通过本课，学生将掌握注释的核心用法，并能在实际编码中养成添加注释的良好习惯。