Python3 注释详解

在 Python3 中，注释是用于解释代码功能、提高可读性的文本，不会被解释器执行。合理使用注释能帮助开发者理解代码逻辑，便于团队协作和后续维护。以下是 Python3 中注释的详细介绍：

单行注释

以#符号开头，从#到行末的所有内容都会被视为注释。常用于解释单行代码或代码块的功能。

 

# 计算两数之和
result = a + b  # 存储计算结果

 

多行注释

Python 没有专门的多行注释语法，但可以使用连续的多个单行注释实现多行注释的效果。

 

 

# 这段代码实现了冒泡排序算法
# 比较相邻元素并交换位置，直到整个数组有序
# 时间复杂度为O(n²)
def bubble_sort(arr):
    n = len(arr)
    for i in range(n):
        for j in range(0, n-i-1):
            if arr[j] > arr[j+1]:
                arr[j], arr[j+1] = arr[j+1], arr[j]
    return arr

 

文档字符串（Docstrings）

用于为模块、类、函数或方法提供文档说明，使用三引号（'''或"""）包裹。可通过对象的__doc__属性访问。

 

def add(a, b):
    """
    计算两个数字的和
    
    参数:
        a (int): 第一个数字
        b (int): 第二个数字
    
    返回:
        int: 两个数字的和
    """
    return a + b

print(add.__doc__)  # 输出文档字符串内容

 

注释规范

1. 保持简洁：注释应简明扼要，避免冗长复杂的解释。
2. 避免冗余：不要为显而易见的代码添加注释，如x = 5 # 将5赋值给x。
3. 使用英文：在开源项目或团队协作中，建议使用英文注释以便全球开发者理解。
4. 更新维护：代码修改时，同步更新相关注释以保持准确性。

特殊注释

1. 编码声明：指定源文件的编码格式，通常位于文件首行。

 

# -*- coding: utf-8 -*-

 

2. Shebang 行：指定 Python 解释器路径，用于 Unix/Linux 系统的可执行 Python 脚本。

 

#!/usr/bin/env python3

3. 类型提示注释：帮助 IDE 和静态分析工具理解变量类型。

age: int = 25  # 变量类型注释
def greet(name: str) -> str:  # 函数参数和返回值类型注释
    return f"Hello, {name}"

注释工具

• pydoc：Python 内置工具，可基于文档字符串生成 HTML 格式的文档。
• Sphinx：流行的 Python 文档生成工具，支持从代码和注释自动生成专业文档。
• flake8/pylint：代码检查工具，可检测注释风格和质量。

合理使用注释是编写高质量代码的重要组成部分，能显著提升代码的可维护性和团队协作效率。