Python3 注释

在 Python 中，注释不会影响程序的执行，但是会使代码更易于阅读和理解。

Python 中的注释有单行注释和多行注释。

单行注释

Python 中单行注释以 # 开头，# 符号后面的所有文本都被视为注释，不会被解释器执行。

实例

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

多行注释

在 Python 中，多行字符串（由三个单引号 ‘’’ 或三个双引号 “”“ 包围的文本块）可以用作多行注释。

1、使用三个单引号

实例

#!/usr/bin/python3

'''
这是多行注释，用三个单引号
这是多行注释，用三个单引号
这是多行注释，用三个单引号
'''
print("Hello, World!")

2、使用三个双引号

实例

#!/usr/bin/python3

"""
这是多行注释，用三个双引号
这是多行注释，用三个双引号
这是多行注释，用三个双引号
"""
print("Hello, World!")

注意：虽然多行字符串在这里被当作多行注释使用，但它实际上是一个字符串，我们只要不使用它，它不会影响程序的运行。

这些字符串在代码中可以被放置在一些位置，而不引起实际的执行，从而达到注释的效果。

多行注释注意事项

在 Python 中，多行注释是由三个单引号 ‘’’ 或三个双引号 “”“ 来定义的，这种注释方式不能嵌套使用。

当你开始一个多行注释块时，Python 会一直将后续的行都当作注释，直到遇到另一组三个单引号或三个双引号。

嵌套多行注释会导致语法错误：

实例（错误示例）

'''
这是外部的多行注释
可以包含一些描述性的内容

    '''
    这是尝试嵌套的多行注释
    会导致语法错误
    '''
'''

在这个例子中，内部的三个单引号并没有被正确识别为多行注释的结束，而是被解释为普通的字符串，这将导致代码结构不正确。

正确做法：使用单行注释嵌套

实例（正确示例）

'''
这是外部的多行注释
可以包含一些描述性的内容

# 这是内部的单行注释
# 可以嵌套在多行注释中
'''

Docstring 文档字符串

Python 的 Docstring（文档字符串）是一种特殊的注释，用于为函数、类、模块等添加文档说明。它类似于 Java 的 Javadoc，但更加强大和灵活。

与普通注释不同，Docstring 可以通过 __doc__ 属性直接访问，也可以使用 help() 函数查看。

基本语法

Docstring 使用三个双引号 """ 或三个单引号 ''' 包围，放在函数、类、模块的开头。

实例

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

# 通过 __doc__ 属性访问
print(add.__doc__)  # 输出: 返回两数之和

使用 help() 查看文档

实例

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

# 使用 help() 函数
help(add)

运行结果预期:

Help on function add in module __main__:

add(a, b)
    返回两数之和

使用 inspect 模块提取文档

Python 的标准库提供了 inspect 模块，可以直接提取文档内容：

实例

import inspect

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

# 使用 inspect.getdoc() 获取文档
print(inspect.getdoc(add))  # 输出: 返回两数之和

运行结果预期:

返回两数之和

多行 Docstring

对于复杂的函数，可以使用多行 Docstring：

实例

def calculate(a, b, operation="add"):
    """
    执行数学运算

    参数:
        a: 第一个数字
        b: 第二个数字
        operation: 操作类型，可选 "add", "subtract", "multiply"

    返回:
        计算结果
    """
    if operation == "add":
        return a + b
    elif operation == "subtract":
        return a - b
    elif operation == "multiply":
        return a * b
    else:
        raise ValueError("不支持的操作")

# 查看完整文档
help(calculate)

运行结果预期:

Help on function calculate in module __main__:

calculate(a, b, operation='add')
    执行数学运算

    参数:
        a: 第一个数字
        b: 第二个数字
        operation: 操作类型，可选 "add", "subtract", "multiply"

    返回:
        计算结果

类的 Docstring

Docstring 也可以用于类：

实例

class Person:
    """人物类，用于表示一个人的基本信息"""

    def __init__(self, name, age):
        """
        初始化人物对象

        参数:
            name: 姓名
            age: 年龄
        """
        self.name = name
        self.age = age

    def introduce(self):
        """介绍这个人"""
        return f"我叫{self.name}，今年{self.age}岁"

# 访问类的文档
print(Person.__doc__)

# 访问方法的文档
print(Person.introduce.__doc__)

运行结果预期:

人物类，用于表示一个人的基本信息
介绍这个人

Docstring 规范

Python 中有多种 Docstring 风格，常用的有：

Google 风格：使用空格缩进，参数和返回值有明确的标签。
Sphinx/reST 风格：使用冒号开头，如 :param name:。
NumPy 风格：与 Google 风格类似，但格式略有不同。

建议在项目中选择一种风格并保持一致。