什么值得买App下载 App ›
连续签到专享现金活动

写代码不写注释,等于给别人挖坑:Python注释的四个层次

代码维护过程中,常出现开发者无法理解自身或他人早期代码逻辑的情况,这往往源于注释的缺失。在Python开发中,注释虽被解释器忽略,却是连接代码逻辑与人类认知的关键桥梁。高质量的注释旨在降低阅读者的认知负担,明确代码功能、设计意图及潜在风险,从而提升代码的可维护性与团队协作效率。
01Python注释的四个层次
  1. 解释“做了什么”
    最基础的注释层面,用于陈述代码块的功能,适用于复杂算法或业务逻辑的说明。例如:在遍历列表筛选数据时,注释应明确指出筛选条件。
    # 遍历列表,找出所有大于100的数,并存入新列表
    result = []
    for num in data:
        if num > 100:
            result.append(num)
  2. 解释“为什么这么做”
    比功能描述更重要的是解释设计决策。当代码逻辑看似反直觉或特定实现是为了规避某些问题时,必须说明原因,以防止后续维护者进行错误的“优化”。
    # 这里必须用while而不是for,因为循环过程中列表长度会动态变化
    i = 0
    while i < len(some_list):
        if condition:
            some_list.pop(i)
        else:
            i += 1
  3. 警示和TODO
    在代码的高风险区域或未完成部分添加标记。警示(WARNING)用于提示可能导致的严重后果(如接口限流),TODO用于标记未来需要优化的功能点。
    # 警告:此接口每秒只能调用一次,超过会被封IP
    time.sleep(1)
    # TODO: 异常处理需区分网络错误和业务错误
  4. 文档字符串(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说明与交互公共函数、类及模块的接口定义

注释体系总结

评论

评论区空态插画

当前文章无评论,是时候发表评论了