Python案例怎么注释代码内容？

wen python案例 2026-06-07 76

Python案例怎么注释代码内容？——从新手到高手的注释全攻略

目录导读

为什么注释如此重要？ – 解释注释的三大核心价值
注释的基本原则 – 写好注释前必须知道的规则
Python注释的3种官方写法 – 单行、多行、文档字符串全解析
实战案例：一个爬虫项目的注释剖析 – 拆解完整案例注释逻辑
常见注释误区与最佳实践 – 避免注释坏习惯，提升代码可读性
问答环节 – 解决你关于注释的5个高频疑惑

为什么注释如此重要？

在Stack Overflow的一项开发者调查中，代码可读性被列为团队协作中最头疼的问题之一，注释正是解决这一痛点的核心工具，它的价值体现在三个层面：

Python案例怎么注释代码内容？

为“未来的自己”减负：3个月后回看代码，没有注释的df['col'] = df['col'].apply(lambda x: x.strip() if x else '')会让你怀疑人生。
降低团队沟通成本：同事无需逐行猜测逻辑，直接通过文档字符串理解函数意图。
提升代码维护效率：根据GitHub统计，有良好注释的Python项目，Bug修复速度平均快34%。

注释不是写给机器看的,是写给人看的。

注释的基本原则

在开始写注释前,先掌握这4条黄金法则：

解释“为什么”，而非“是什么”：# 将字符串转换为整数是废话，# 防止用户输入空字符串导致的类型错误才是有价值的注释。
保持与代码同步：最可怕的不是没注释，而是过期的注释，修改代码后务必更新对应注释。
避免“画蛇添足”：如果代码本身足够清晰（如age = 25），不需要写# 设置年龄为25。
使用英文还是中文？：国内团队建议用中文，但混用英文关键字（如TODO、FIXME）是通用规范。

Python注释的3种官方写法

1 单行注释（）

用于简短说明,通常放在代码上方或同行末尾。

# 按文件名排序，忽略大小写
files.sort(key=lambda f: f.lower())

2 多行注释（或）

虽然Python不内置多行注释符号,但官方通常用三个双引号实现，注意这不等于文档字符串。

"""
这个循环用于： 
1. 过滤掉空行 
2. 将每行首尾空格去掉 
3. 统计有效行数
"""

3 文档字符串（Docstring）—— 最重要的注释

用于模块、类、函数的头部，可通过help()或__doc__调用，PEP 257规定了标准格式。

def calculate_bmi(weight: float, height: float) -> float:
    """
    计算身体质量指数（BMI）
    Args:
        weight (float): 体重，单位千克
        height (float): 身高，单位米
    Returns:
        float: BMI指数，保留两位小数
    Examples:
        >>> calculate_bmi(70, 1.75)
        22.86
    """
    return round(weight / (height ** 2), 2)

实战案例：一个爬虫项目的注释剖析

假设我们有一个爬取电商商品信息的脚本,下面展示“差注释”与“优注释”的对比。

差注释示例（不要学）：

def get_data(url):
    # 发送请求
    r = requests.get(url)
    # 解析
    soup = BeautifulSoup(r.text, 'html.parser')
    # 提取标题= soup.find('h1').text
    # 返回
    return title

优注释示例（应该这样写）：

import requests
from bs4 import BeautifulSoup
def extract_product_title(url: str) -> str:
    """
    从商品详情页提取产品标题
    目标网站：jd.com（京东）
    注意：该页面使用动态渲染的 <h1 class="item-title"> 标签，
    若遇到反爬，需要切换到 Selenium 方案。
    Args:
        url (str): 商品详情页链接
    Returns:
        str: 商品标题，若提取失败返回空字符串
    Raises:
        requests.exceptions.RequestException: 当网络请求超时或连接失败时抛出
    """
    try:
        # 设置请求头模拟浏览器，防止被屏蔽
        headers = {
            'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36'
        }
        # 设置10秒超时，避免无限等待
        response = requests.get(url, headers=headers, timeout=10)
        response.raise_for_status()  # 检查HTTP状态码
        # 使用BeautifulSoup解析HTML，注意京东的标题标签是 h1
        soup = BeautifulSoup(response.text, 'html.parser')
        title_tag = soup.find('h1', class_='item-title')
        # 若标签存在则提取文本，否则返回空字符串
        if title_tag:
            return title_tag.get_text(strip=True)
        return ""
    except requests.exceptions.Timeout:
        # 记录超时错误到日志，便于排查
        print(f"[ERROR] 请求超时: {url}")
        return ""
    except requests.exceptions.RequestException as e:
        print(f"[ERROR] 网络错误: {e}")
        return ""

关键在于：优注释不仅描述了做了什么，还说明了为什么这样做（如超时设置、反爬策略）、潜在风险（动态渲染）和错误处理（日志记录）。