一、什么是注释？
注释是代码中的“说明文字”——写给人看的，Python解释器会完全忽略它们。
注释的作用：
二、注释的三种写法
1. 单行注释（最常用）
使用 # 符号，从#开始到行尾都是注释。
# 这是单行注释print("Hello World") # 这也是注释（放在代码后面）
案例：
# 计算圆的面积radius = 5# 半径5厘米pi = 3.14159# 圆周率area = pi * radius * radius # 面积公式print(f"面积：{area}平方厘米")
2. 多行注释（两种写法）
写法1：连续多个#
# 这是多行注释# 每一行都要加## 适合少量行数
写法2：三引号（推荐）
"""这是多行注释可以写很长很长三对双引号或单引号都可以"""
案例：函数说明
"""计算器函数模块包含：加减乘除四个基本运算作者：张三创建日期：2024-01-15"""defadd(a, b):"""返回两个数的和"""return a + b
3. 文档字符串（Docstring）
写在函数/类/模块开头的三引号字符串，可以通过help()查看。
defgreet(name):""" 向用户问好 参数： name: 用户名（字符串） 返回： 问候语（字符串） 示例： >>> greet("小明") '你好，小明！' """returnf"你好，{name}！"# 查看文档help(greet)
输出：
Help on function greet in module __main__:greet(name) 向用户问好 参数： name: 用户名（字符串） 返回： 问候语（字符串） 示例： >>> greet("小明") '你好，小明！'
三、5个必学的注释场景
场景1：文件头注释
#!/usr/bin/env python3# -*- coding: utf-8 -*-"""文件名：calculator.py描述：简易计算器程序作者：王小明版本：1.0.0日期：2024-01-15"""
场景2：函数注释
defcalculate_bmi(weight, height):""" 计算身体质量指数(BMI) 计算公式：体重(kg) / 身高(m)的平方 参数: weight: 体重，单位公斤 height: 身高，单位米 返回: BMI值（浮点数） 18.5以下：偏瘦 18.5-24：正常 24-28：偏胖 28以上：肥胖 """return weight / (height ** 2)
场景3：类注释
classStudent:"""学生信息类"""def__init__(self, name, age):"""初始化学生"""self.name = nameself.age = agedefstudy(self, course):"""学习指定课程"""print(f"{self.name}正在学习{course}")
场景4：代码逻辑注释
# 步骤1：获取用户输入name = input("请输入姓名：")age = int(input("请输入年龄："))# 步骤2：验证年龄合法性if age < 0:print("年龄不能为负数！") # 防御性编程elif age > 150:print("年龄超过人类极限！") # 防止异常输入else:# 步骤3：显示结果print(f"你好{name}，你今年{age}岁")
场景5：调试注释（临时屏蔽代码）
# 调试时临时注释掉某些代码# print("这行先不运行")# print("这行也不运行")print("只有这行运行") # 快速测试功能
四、注释的三大黄金法则
法则1：注释“为什么”，不是“是什么”
❌ 坏注释：
i = i + 1# i加1
✅ 好注释：
i = i + 1# 跳过管理员ID（管理员ID固定为1001）
法则2：代码自解释，尽量少注释
❌ 坏注释：
# 如果年龄大于等于18岁if age >= 18:# 打印成年print("成年")
✅ 好代码：
ADULT_AGE = 18if age >= ADULT_AGE:print("成年")
法则3：注释要及时更新
❌ 危险注释：
# 固定税率15%（实际代码已改为20%）tax_rate = 0.20# 注释没改，坑队友！
✅ 正确做法：
# 当前增值税率为20%（2024年最新）tax_rate = 0.20
五、不同场景注释示例
案例1：配置文件注释
# ============= 数据库配置 =============DB_HOST = "localhost"# 数据库服务器地址DB_PORT = 3306# MySQL默认端口DB_USER = "root"# 用户名（生产环境需修改）DB_PASS = "123456"# ⚠️ 临时密码，上线前必须改！# ====================================
案例2：算法注释
defbinary_search(arr, target):""" 二分查找算法 原理： 1. 找到数组中间位置 2. 比较中间值和目标值 3. 相等：返回下标 4. 目标值小：在左半部分继续查找 5. 目标值大：在右半部分继续查找 时间复杂度：O(log n) 空间复杂度：O(1) """ left, right = 0, len(arr) - 1while left <= right: mid = (left + right) // 2if arr[mid] == target:return midelif arr[mid] < target: left = mid + 1# 目标在右边else: right = mid - 1# 目标在左边return -1# 未找到
案例3：TODO注释（待办事项）
defprocess_data(data):# TODO: 添加数据验证逻辑# FIXME: 这段代码处理大文件时内存占用过高# BUG: 中文路径会报错，下个版本修复# 临时方案，后续替换为正式接口 result = data * 2return result
案例4：正则表达式注释
import re# 手机号正则：1开头的11位数字phone_pattern = re.compile(r""" ^1 # 以1开头 [3-9] # 第二位：3-9 \d{9} # 后面9位数字 $ # 结束""", re.VERBOSE) # VERBOSE模式允许写注释
六、新手常见错误
错误1：注释与代码不符
# ❌ 说好的返回姓名，实际返回年龄defget_name():return age
错误2：过度注释
# ❌ 每一行都注释，反而看不清a = 1# 把1赋值给ab = 2# 把2赋值给bc = a + b # a加b赋值给cprint(c) # 打印c
错误3：注释掉的代码不及时清理
# 以下代码已废弃，但不敢删# old_function1()# old_function2()# old_function3()# old_function4()
错误4：中文乱码
# 没有声明编码格式，中文注释可能报错# 解决方法：文件头部加# -*- coding: utf-8 -*-
七、IDE快捷键
VS Code / PyCharm：
- •
Ctrl + / → 快速注释/取消注释当前行
Jupyter Notebook：
八、总结：写好注释的三句话
- 1. 注释是写给“人”看的——写清楚为什么要这么写
- 3. 注释和代码一样需要维护——改了代码一定要改注释
最后记住：
# 写注释不是为了机器，是为了未来的自己# 以及那个不得不接手你代码的可怜同事
练习： 找一段你自己写的代码，尝试给每个函数加上文档字符串，给关键逻辑加上注释。坚持一周，你会养成写注释的好习惯。
10个月宝宝每天需要喝多少奶粉？
