Python注释的写法——写好代码的第一步

一、什么是注释？

注释是代码中的“说明文字”——写给人看的，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 + / → 快速注释/取消注释当前行
• • Alt + Shift + A → 块注释

Jupyter Notebook：

• • Ctrl + / → 注释/取消注释

八、总结：写好注释的三句话

1. 1. 注释是写给“人”看的——写清楚为什么要这么写
2. 2. 好的代码本身就是注释——能不用注释就别用
3. 3. 注释和代码一样需要维护——改了代码一定要改注释

最后记住：

# 写注释不是为了机器，是为了未来的自己# 以及那个不得不接手你代码的可怜同事

练习： 找一段你自己写的代码，尝试给每个函数加上文档字符串，给关键逻辑加上注释。坚持一周，你会养成写注释的好习惯。