写代码不写注释,等于给别人挖坑:Python注释的四个层次
代码维护过程中,常出现开发者无法理解自身或他人早期代码逻辑的情况,这往往源于注释的缺失。在Python开发中,注释虽被解释器忽略,却是连接代码逻辑与人类认知的关键桥梁。高质量的注释旨在降低阅读者的认知负担,明确代码功能、设计意图及潜在风险,从而提升代码的可维护性与团队协作效率。
01Python注释的四个层次
- 解释“做了什么”
最基础的注释层面,用于陈述代码块的功能,适用于复杂算法或业务逻辑的说明。例如:在遍历列表筛选数据时,注释应明确指出筛选条件。# 遍历列表,找出所有大于100的数,并存入新列表
result = []
for num in data:
if num > 100:
result.append(num) - 解释“为什么这么做”
比功能描述更重要的是解释设计决策。当代码逻辑看似反直觉或特定实现是为了规避某些问题时,必须说明原因,以防止后续维护者进行错误的“优化”。# 这里必须用while而不是for,因为循环过程中列表长度会动态变化
i = 0
while i < len(some_list):
if condition:
some_list.pop(i)
else:
i += 1 - 警示和TODO
在代码的高风险区域或未完成部分添加标记。警示(WARNING)用于提示可能导致的严重后果(如接口限流),TODO用于标记未来需要优化的功能点。# 警告:此接口每秒只能调用一次,超过会被封IP
time.sleep(1)
# TODO: 异常处理需区分网络错误和业务错误 - 文档字符串(Docstring)
用于函数、类或模块的详细说明。标准的三引号格式可通过help()函数或IDE直接调取,是API接口文档的重要组成部分。def calculate_bmi(weight, height):
"""
根据体重和身高计算BMI指数。
参数:
weight: 体重(千克)
height: 身高(米)
返回:
BMI数值(浮点数)
"""
return weight / (height ** 2)
02反面教材与最佳实践
注释规范对比
代码即注释
优先使用清晰的命名表达意图,减少冗余注释。
示例:
total_price = unit_price * quantity


废话式注释
注释仅重复代码字面意思,无信息增量。
示例:
x = x + 1 # 把x加1
03综合实战示例
以下示例展示了在实际开发中如何综合运用文档字符串、行内注释及警示注释,构建一个健壮且易于理解的函数。
import requests
def fetch_weather(city_name, retry=3):
"""
从某天气API获取城市当前温度。
参数:
city_name: 城市名称(字符串)
retry: 失败重试次数,默认3次
返回:
温度(整数摄氏度),如果失败返回None
"""
url = f"https://api.weather.com/temp?city={city_name}"
# 重试机制,因为网络请求可能不稳定
for attempt in range(retry):
try:
response = requests.get(url, timeout=5)
# 200表示成功
if response.status_code == 200:
data = response.json()
# API返回的temperature单位是开尔文,转换为摄氏度
kelvin = data['temp']
celsius = kelvin - 273.15
return int(round(celsius))
except requests.exceptions.Timeout:
# 超时后继续下一次重试,不立刻报错
continue
# 所有重试都失败,返回None(调用方需处理空值情况)
return None| 注释层次 | 核心作用 | 典型应用场景 |
|---|---|---|
| 做什么 | 解释代码功能 | 复杂算法实现、业务逻辑处理 |
| 为什么 | 解释设计决策 | 反直觉代码、特定技术选型原因 |
| 警示/TODO | 提醒风险和待办 | 关键节点的错误预防、功能规划 |
| 文档字符串 | API说明与交互 | 公共函数、类及模块的接口定义 |
注释体系总结
当前文章无评论,是时候发表评论了