Python 注释

7年前端辞职转AI2026-04-14 15:58

Python 注释

目录

  1. 什么是注释
  2. 单行注释
  3. 多行注释
  4. [文档字符串 (Docstrings)](#文档字符串 (Docstrings) "#%E6%96%87%E6%A1%A3%E5%AD%97%E7%AC%A6%E4%B8%B2-docstrings")
  5. 注释的最佳实践
  6. 常见错误和注意事项

什么是注释

注释是代码中不会被Python解释器执行的部分,主要用于:

  • 解释代码的功能和逻辑
  • 提高代码的可读性
  • 便于团队协作和维护
  • 临时禁用某段代码(调试时)

单行注释

基本语法

使用 # 符号创建单行注释:

python 复制代码 
# 这是一个单行注释
print("Hello, World!")  # 这也是一个注释(行尾注释)

# 变量声明
name = "Alice"  # 存储用户姓名
age = 25        # 存储用户年龄

使用技巧

python 复制代码 
# ✓ 好的做法:注释说明"为什么"而不是"是什么"
# 计算复利,年利率为5%
interest = principal * (1 + 0.05) ** years

# ✗ 不好的做法:重复代码显而易见的功能
x = x + 1  # 将x加1

多行注释

Python没有专门的多行注释语法,但有以下几种方式:

方法1:多个单行注释

python 复制代码 
# 这是第一行注释
# 这是第二行注释
# 这是第三行注释
result = calculate(a, b, c)

方法2:使用三引号字符串(未赋值时)

python 复制代码 
"""
这是一个多行注释
可以写很多行内容
用于详细说明复杂逻辑
"""
def complex_function():
    pass

注意:这种方式实际上是创建了字符串对象,只是没有被赋值给变量。在函数、类或模块开头使用时,它会成为文档字符串(docstring)。

文档字符串 (Docstrings)

文档字符串是用于记录模块、类、函数功能的特殊字符串,使用三引号 """ 或 ''' 包围。

函数文档字符串

python 复制代码 
def add_numbers(a, b):
    """
    计算两个数的和

    Args:
        a (int/float): 第一个数字
        b (int/float): 第二个数字

    Returns:
        int/float: 两个数字的和

    Example:
        >>> add_numbers(3, 5)
        8
        >>> add_numbers(2.5, 3.5)
        6.0
    """
    return a + b

类文档字符串

python 复制代码 
class Student:
    """
    学生类,用于管理学生信息

    Attributes:
        name (str): 学生姓名
        age (int): 学生年龄
        grade (float): 学生成绩
    """

    def __init__(self, name, age, grade):
        """
        初始化学生对象

        Args:
            name (str): 学生姓名
            age (int): 学生年龄
            grade (float): 学生成绩
        """
        self.name = name
        self.age = age
        self.grade = grade

模块文档字符串

python 复制代码 
"""
math_utils.py - 数学工具模块

提供常用的数学计算功能,包括:
- 基本运算
- 统计计算
- 几何计算

Author: Your Name
Version: 1.0
"""

def calculate_average(numbers):
    """计算平均值"""
    return sum(numbers) / len(numbers)

查看文档字符串

python 复制代码 
# 使用 help() 函数
help(add_numbers)

# 使用 __doc__ 属性
print(add_numbers.__doc__)

# 使用 dir() 查看所有属性和方法
dir(Student)

注释的最佳实践

1. 注释应该解释"为什么",而不是"是什么"

python 复制代码 
# ✓ 好:解释原因
# 使用二分查找以提高搜索效率(数据已排序)
index = binary_search(sorted_list, target)

# ✗ 不好:重复代码
# 调用二分查找函数
index = binary_search(sorted_list, target)

2. 保持注释简洁明了

python 复制代码 
# ✓ 好:简洁清晰
# 过滤掉无效数据(None和空值)
valid_data = [x for x in data if x is not None and x != '']

# ✗ 不好:冗长啰嗦
# 这里我们使用列表推导式来遍历data中的每一个元素x,
# 然后检查x是否不等于None并且x也不等于空字符串,
# 如果满足条件就保留这个元素
valid_data = [x for x in data if x is not None and x != '']

3. 及时更新注释

python 复制代码 
# 当代码改变时,记得更新相关注释
# 旧注释:计算两个数的和
# 新代码:计算三个数的和
def add_numbers(a, b, c):  # ✗ 注释与代码不匹配
    return a + b + c

4. 使用TODO注释标记待办事项

python 复制代码 
# TODO: 添加输入验证
# FIXME: 修复除零错误
# HACK: 临时解决方案,需要重构
# NOTE: 重要的注意事项
# WARNING: 潜在的问题

def process_data(data):
    # TODO: 添加异常处理
    # FIXME: 当前实现效率较低
    result = [x * 2 for x in data]
    return result

5. 复杂的算法必须添加注释

python 复制代码 
def quicksort(arr):
    """快速排序算法"""
    if len(arr) <= 1:
        return arr

    # 选择基准元素(中间位置)
    pivot = arr[len(arr) // 2]

    # 将数组分为三部分:小于、等于、大于基准的元素
    left = [x for x in arr if x < pivot]
    middle = [x for x in arr if x == pivot]
    right = [x for x in arr if x > pivot]

    # 递归排序左右两部分,然后合并
    return quicksort(left) + middle + quicksort(right)

6. 避免过度注释

python 复制代码 
# ✗ 不好:过度注释
# 定义一个变量x
x = 10
# 定义一个变量y
y = 20
# 计算x和y的和
result = x + y

# ✓ 好:只在必要时注释
# 配置参数
max_retries = 10
timeout = 30  # 秒

常见错误和注意事项

1. 中文注释的编码问题

python 复制代码 
# -*- coding: utf-8 -*-
# 在Python 2中需要声明编码,Python 3默认支持UTF-8

# 现在可以放心使用中文注释
姓名 = "张三"  # 存储用户姓名

2. 注释掉的代码应及时删除

python 复制代码 
# ✗ 不好:保留大量注释代码
# old_result = calculate_v1(data)
# old_result = calculate_v2(data)
# old_result = calculate_v3(data)
result = calculate_v4(data)

# ✓ 好:使用版本控制系统(如Git)管理历史代码
result = calculate_v4(data)

3. 避免误导性注释

python 复制代码 
# ✗ 危险:注释与代码不一致
# 返回用户列表
return user_dict  # 实际返回的是字典,不是列表

# ✓ 好:注释准确描述代码行为
# 返回用户字典(键为用户ID,值为用户信息)
return user_dict

4. 调试时的临时注释

python 复制代码 
# 调试时可以临时注释代码
def process_items(items):
    for item in items:
        # print(f"Processing: {item}")  # 调试输出
        result = transform(item)
        # print(f"Result: {result}")    # 调试输出
    return results

实战示例

示例1:完整的函数注释

python 复制代码 
def calculate_bmi(weight, height):
    """
    计算身体质量指数(BMI)

    BMI是衡量人体胖瘦程度的常用指标,计算公式为:
    BMI = 体重(kg) / 身高(m)²

    Args:
        weight (float): 体重,单位千克(kg)
        height (float): 身高,单位米(m)

    Returns:
        float: BMI值,保留两位小数

    Raises:
        ValueError: 当体重或身高为非正数时抛出
        TypeError: 当输入不是数字类型时抛出

    Example:
        >>> calculate_bmi(70, 1.75)
        22.86
        >>> calculate_bmi(60, 1.65)
        22.04

    Note:
        BMI分类标准:
        - 偏瘦: < 18.5
        - 正常: 18.5 - 23.9
        - 偏胖: 24.0 - 27.9
        - 肥胖: >= 28.0
    """
    # 输入验证
    if not isinstance(weight, (int, float)) or not isinstance(height, (int, float)):
        raise TypeError("体重和身高必须是数字类型")

    if weight <= 0 or height <= 0:
        raise ValueError("体重和身高必须为正数")

    # 计算BMI
    bmi = weight / (height ** 2)

    # 保留两位小数
    return round(bmi, 2)

示例2:类和方法的完整注释

python 复制代码 
class BankAccount:
    """
    银行账户类

    提供基本的银行账户操作功能,包括存款、取款和查询余额。

    Attributes:
        account_holder (str): 账户持有人姓名
        balance (float): 账户余额
        account_number (str): 账号

    Example:
        >>> account = BankAccount("张三", "123456789")
        >>> account.deposit(1000)
        >>> account.withdraw(200)
        >>> account.get_balance()
        800.0
    """

    def __init__(self, account_holder, account_number, initial_balance=0):
        """
        初始化银行账户

        Args:
            account_holder (str): 账户持有人姓名
            account_number (str): 账号
            initial_balance (float): 初始余额,默认为0
        """
        self.account_holder = account_holder
        self.account_number = account_number
        self.balance = initial_balance

    def deposit(self, amount):
        """
        存款

        Args:
            amount (float): 存款金额,必须为正数

        Returns:
            float: 存款后的余额

        Raises:
            ValueError: 当存款金额为负数时抛出
        """
        if amount <= 0:
            raise ValueError("存款金额必须为正数")

        self.balance += amount
        return self.balance

    def withdraw(self, amount):
        """
        取款

        Args:
            amount (float): 取款金额,必须为正数且不超过余额

        Returns:
            float: 取款后的余额

        Raises:
            ValueError: 当取款金额为负数或超过余额时抛出
        """
        if amount <= 0:
            raise ValueError("取款金额必须为正数")

        if amount > self.balance:
            raise ValueError("余额不足")

        self.balance -= amount
        return self.balance

    def get_balance(self):
        """
        查询余额

        Returns:
            float: 当前账户余额
        """
        return self.balance

总结

关键要点

  1. 单行注释 :使用 # 符号
  2. 多行注释 :使用多个 # 或三引号字符串
  3. 文档字符串 :使用三引号 """ 记录模块、类、函数的文档
  4. 注释原则 :
    • 解释"为什么"而不是"是什么"
    • 保持简洁明了
    • 及时更新
    • 避免过度注释
    • 复杂算法必须注释

推荐工具

  • pydocstyle:检查docstring风格
  • Sphinx:从docstring生成文档
  • pylint/flake8:代码检查工具,包含注释规范检查

学习资源

记住:好的代码本身就是最好的文档,注释应该是代码的补充,而不是替代品。编写清晰、自解释的代码,配合必要的注释,才能创造出易于维护的高质量代码。

相关推荐
xcjbqd04 小时前
CSS如何给Bootstrap侧边菜单加图标_使用font-awesome结合CSS
jvm·数据库·python
坐吃山猪4 小时前
Python09_正则表达式
开发语言·python·正则表达式
deephub4 小时前
从检索到回答：RAG 流水线中三个被忽视的故障点
人工智能·python·大语言模型·向量检索·rag
yiruwanlu4 小时前
乡村文旅设计师推荐：建筑设计能力筛选要点解析
python·ui
站大爷IP4 小时前
Python 操作 Word 页眉页脚完整指南
python
SomeB1oody4 小时前
【Python深度学习】2.1. 卷积神经网络(CNN)模型理论(基础)：卷积运算、池化、ReLU函数
开发语言·人工智能·python·深度学习·机器学习·cnn
solicitous5 小时前
python数据抓取
python
HaiXCoder5 小时前
Kotlin vs Python 知识点对照表
python
I疯子5 小时前
2026-04-13 打卡第 6 天
开发语言·python
热门推荐
012026年4月技术前沿：AI大模型爆发、智能体革命与量子安全新纪元02GitHub 镜像站点03一周AI热点速览（2026.03.31-04.06）：GPT-6曝光、谷歌开源Gemma 4、资本狂飙与模型军备竞赛04GPT-6核心能力解析及与现有主流大模型对比05基于 Docker 部署 Hermes Agent 并接入飞书机器人的完整指南06免费！不限量！用opencode接入英伟达（NVIDIA）大模型，轻松打造你的 AI 编程助手07从限购到畅通：GLM-5.1 Coding Plan接入攻略08零成本！Ollama本地部署国产大模型全指南（支持Kimi-K2.5/GLM-5/Qwen，新手秒上手）09LLM Wiki：让大模型替你打理知识库的完整指南10CodeBuddy与WorkBuddy深度对比：腾讯两款AI工具差异及实操指南