Python注释详解

注释是Python代码中非常重要的组成部分，它们用于解释代码的功能、提高代码的可读性和可维护性。本文将详细介绍Python中的各种注释类型、语法规则和最佳实践。

一、注释概述

1. 什么是注释？

注释是在程序中添加的解释性文本，用于说明代码的功能、实现方法或其他重要信息。注释不会被Python解释器执行，只是作为代码的辅助说明存在。

2. 注释的作用

提高可读性：帮助其他开发者（或未来的自己）理解代码的功能和设计意图
便于维护：当代码需要修改时，注释可以快速提示代码的用途和实现细节
辅助调试：可以暂时注释掉部分代码，用于定位问题
记录信息：记录代码的修改历史、作者、版权信息等

3. 注释的基本原则

清晰明了：注释应该简洁、准确地表达代码的功能
避免冗余：不要注释显而易见的代码
保持更新：当代码修改时，相应的注释也应该更新
使用统一风格：在项目中使用一致的注释风格

二、单行注释

单行注释是Python中最基本的注释类型，使用#符号开头。

1. 语法

# 这是一个单行注释
print("Hello, World!")  # 这也是一个单行注释

2. 使用场景

为代码行添加简短说明
解释变量的用途或值的含义
标记代码的状态（如TODO、FIXME等）
暂时注释掉不需要执行的代码

3. 示例

# 定义一个变量，存储用户年龄
age = 30

# 检查用户是否成年
if age >= 18:  # 18岁及以上为成年
    print("成年人")
else:
    print("未成年人")

# TODO: 实现用户登录功能
# login()

三、多行注释

当需要添加较长的注释时，可以使用多行注释。Python中没有专门的多行注释语法，但可以使用三个单引号'''或三个双引号"""来实现。

1. 语法

'''这是一个多行注释可以跨越多行'''"""这也是一个多行注释使用双引号"""

2. 使用场景

为模块、函数或类添加详细说明
解释复杂算法的实现原理
记录代码的修改历史
包含版权信息或许可证

3. 示例

'''文件：calculator.py作者：张荣殿创建时间：2026-01-18功能：提供基本的数学运算功能包括：加法、减法、乘法、除法'''''

# 复杂算法注释
'''
快速排序算法实现步骤：1. 选择一个基准元素2. 将数组分为小于基准和大于基准的两部分3. 递归地对两部分进行排序4. 合并结果
'''def quick_sort(arr):
    # 算法实现
    pass

四、文档字符串（Docstring）

文档字符串是一种特殊的注释，用于为模块、函数、类或方法提供文档说明。文档字符串可以通过__doc__属性访问。

1. 语法

文档字符串使用三个单引号'''或三个双引号"""括起来，可以是单行或多行。

# 单行文档字符串
def add(a, b):
    """返回两个数的和"""
    return a + b

# 多行文档字符串
def divide(a, b):
    """返回两个数的商

    参数:
        a (float): 被除数
        b (float): 除数

    返回:
        float: 商

    异常:
        ZeroDivisionError: 当除数为零时
    """
    if b == 0:
        raise ZeroDivisionError("除数不能为零")
    return a / b

2. 文档字符串约定

Python社区常用的文档字符串格式有三种：

(1) Google风格

def function(param1, param2):
    """函数功能描述

    参数:
        param1 (int): 参数1的描述
        param2 (str): 参数2的描述

    返回:
        bool: 返回值的描述
    """
    pass

(2) NumPy/SciPy风格

def function(param1, param2):
    """函数功能描述

    详细的功能描述...

    参数
    ----------
    param1 : int
        参数1的详细描述
    param2 : str
        参数2的详细描述

    返回
    -------
    result : bool
        返回值的详细描述

    示例
    --------
    >>> function(1, "test")
    True
    """
    pass

(3) reStructuredText (reST) 风格

def function(param1, param2):
    """函数功能描述

    :param param1: 参数1的描述
    :type param1: int
    :param param2: 参数2的描述
    :type param2: str
    :return: 返回值的描述
    :rtype: bool
    """
    pass

3. 文档字符串的访问

可以使用__doc__属性访问对象的文档字符串：

def add(a, b):
    """返回两个数的和"""
    return a + b

print(add.__doc__)  # 输出：返回两个数的和

4. 文档生成工具

文档字符串可以使用工具自动生成文档：

Sphinx：Python官方推荐的文档生成工具，支持reST格式
pydoc：Python内置的文档生成工具
Doxygen：支持多种编程语言的文档生成工具

五、行内注释

行内注释是写在代码行末尾的注释，用于解释该行代码的具体功能。

1. 语法

x = 10  # 初始化变量x为10
y = x * 2  # 计算x的两倍

2. 使用场景

解释复杂的单行代码
说明特殊的实现细节
标记需要注意的代码行

3. 最佳实践

行内注释应该简洁明了，避免过长
注释与代码之间应该有足够的空格（通常4个空格）
只在必要时使用行内注释，不要注释显而易见的代码

六、特殊注释

Python中还有一些特殊的注释，用于控制解释器的行为或提供额外信息。

1. 编码声明注释

在Python 3中，默认编码是UTF-8，但如果使用其他编码，可以在文件开头添加编码声明：

# -*- coding: gbk -*-  # 使用GBK编码

# 或

# coding=utf-8  # 使用UTF-8编码

2. 解释器路径注释

在Unix/Linux系统中，可以在脚本开头添加shebang行，指定脚本的解释器路径：

#!/usr/bin/env python3  # 使用系统默认的Python 3解释器

#!/usr/bin/python3  # 使用特定路径的Python 3解释器

3. 类型注释

Python 3.5+支持类型注释，可以指定变量、函数参数和返回值的类型：

# 变量类型注释
name: str = "Python"
age: int = 30
height: float = 1.75

# 函数类型注释
def add(a: int, b: int) -> int:
    """返回两个整数的和"""
    return a + b

类型注释不会影响代码的执行，但可以提高代码的可读性，并用于静态类型检查工具（如mypy）。

七、注释的最佳实践

1. 什么时候需要注释？

复杂的算法：解释算法的原理和实现步骤
特殊的设计决策：说明为什么选择某种实现方式
潜在的问题：提醒可能出现的问题或限制
不直观的代码：解释代码的作用和用途
公共API：为模块、函数、类等提供文档

2. 什么时候不需要注释？

显而易见的代码：不要注释简单明了的代码
代码的重复描述：不要简单地重复代码的功能
过时的注释：不要保留与当前代码不符的注释
过多的注释：不要过度注释，保持代码的简洁

3. 注释的风格指南

(1) PEP 8 注释规范

PEP 8是Python的代码风格指南，其中包含了关于注释的建议：

单行注释使用#，后面跟一个空格
多行注释使用三个引号
文档字符串应该清晰地描述对象的功能
行内注释应该与代码之间有4个空格

(2) 注释的格式化

注释应该使用清晰、简洁的语言
保持注释的长度适中（通常不超过80个字符）
使用一致的缩进和换行
对于长注释，应该适当分段

4. 常见的注释标记

TODO：标记需要完成的任务
FIXME：标记需要修复的问题
BUG：标记已知的bug
NOTE：标记需要注意的事项
XXX：标记危险或需要改进的代码

def calculate_price(price, discount):
    # TODO: 实现折扣计算逻辑
    # FIXME: 处理discount为负数的情况
    # NOTE: price参数应该是正数
    return price * (1 - discount)

八、注释的工具支持

1. 代码编辑器的注释功能

大多数代码编辑器都提供了方便的注释功能：

VS Code：选中代码后按Ctrl + /（Windows/Linux）或Cmd + /（macOS）添加/删除注释
PyCharm：选中代码后按Ctrl + /添加/删除单行注释，按Ctrl + Shift + /添加/删除块注释
Sublime Text：选中代码后按Ctrl + /添加/删除注释

2. 静态类型检查工具

mypy：检查Python代码的类型注释
pytype：Google开发的Python类型检查工具
pyre-check：Facebook开发的Python类型检查工具

3. 文档生成工具

Sphinx：生成高质量的文档
pydoc：生成HTML或文本格式的文档
Docutils：将reST格式的文档转换为其他格式

4. 代码质量工具

pylint：检查代码质量，包括注释的完整性
flake8：检查代码风格和质量
black：自动格式化Python代码，包括注释

九、注释的常见错误

1. 注释与代码不一致

当代码修改后，没有更新相应的注释，导致注释与代码不符。

# 计算两个数的和（过时的注释）
def multiply(a, b):  # 现在函数是计算乘积
    return a * b

2. 过度注释

注释过多，导致代码可读性下降。

# 定义变量x为10
x = 10  # 将x赋值为10
# 打印x的值
print(x)  # 输出x

3. 注释重复代码

注释只是简单地重复代码的功能，没有提供额外信息。

def add(a, b):
    """将a和b相加并返回结果"""
    return a + b  # 返回a加b的结果

4. 不清晰的注释

注释使用模糊或不明确的语言，无法帮助理解代码。

# 处理数据（不清晰的注释）
def process_data(data):
    # 做一些处理
    result = []
    for item in data:
        # 处理每个项目
        result.append(item * 2)
    return result

十、总结

Python注释是提高代码可读性和可维护性的重要工具，主要包括：

单行注释：使用#开头，用于简短说明
多行注释：使用三个引号，用于较长的说明
文档字符串：特殊的多行注释，用于为模块、函数、类等提供文档
行内注释：写在代码行末尾的注释，用于解释具体代码
特殊注释：包括编码声明、解释器路径和类型注释等

使用注释时，应该遵循以下原则：

注释应该清晰明了，提供有用的信息
避免过度注释和重复注释
保持注释与代码的一致性
遵循PEP 8等代码风格指南
使用适当的注释标记（如TODO、FIXME等）

通过合理使用注释，可以使代码更容易理解和维护，提高开发效率和代码质量。

发布网站：荣殿教程（zhangrongdian.com）

作者：张荣殿

Python注释详解

一、注释概述

1. 什么是注释？

2. 注释的作用

3. 注释的基本原则

二、单行注释

1. 语法

2. 使用场景

3. 示例

三、多行注释

1. 语法

2. 使用场景

3. 示例

四、文档字符串（Docstring）

1. 语法

2. 文档字符串约定

(1) Google风格

(2) NumPy/SciPy风格

(3) reStructuredText (reST) 风格

3. 文档字符串的访问

4. 文档生成工具

五、行内注释

1. 语法

2. 使用场景

3. 最佳实践

六、特殊注释

1. 编码声明注释

2. 解释器路径注释

3. 类型注释

七、注释的最佳实践

1. 什么时候需要注释？

2. 什么时候不需要注释？

3. 注释的风格指南

(1) PEP 8 注释规范

(2) 注释的格式化

4. 常见的注释标记

八、注释的工具支持

1. 代码编辑器的注释功能

2. 静态类型检查工具

3. 文档生成工具

4. 代码质量工具

九、注释的常见错误

1. 注释与代码不一致

2. 过度注释

3. 注释重复代码

4. 不清晰的注释

十、总结

关注我们的微信公众号