单行注释#

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

实例#

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

多行注释#

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

实例#

1
#!/usr/bin/python3
2

3
'''
4
这是多行注释，用三个单引号
5
这是多行注释，用三个单引号
6
这是多行注释，用三个单引号
7
'''
8
print("Hello, World!")

实例#

1
#!/usr/bin/python3
2

3
"""
4
这是多行注释，用三个双引号
5
这是多行注释，用三个双引号
6
这是多行注释，用三个双引号
7
"""
8
print("Hello, World!")

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

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

实例（错误示例）#

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

5
'''
6
这是尝试嵌套的多行注释
7
会导致语法错误
8
'''
9
'''

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

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

实例（正确示例）#

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

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

Docstring 文档字符串#

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

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

实例#

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

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

实例#

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

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

运行结果预期:

1
Help on function add in module __main__:
2

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

实例#

1
import inspect
2

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

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

运行结果预期:

1
返回两数之和

实例#

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

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

10
    返回:
11
        计算结果
12
    """
13
    if operation == "add":
14
        return a + b
15
    elif operation == "subtract":
16
        return a - b
17
    elif operation == "multiply":
18
        return a * b
19
    else:
20
        raise ValueError("不支持的操作")
21

22
# 查看完整文档
23
help(calculate)

运行结果预期:

1
Help on function calculate in module __main__:
2

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

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

11
    返回:
12
        计算结果

实例#

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

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

8
        参数:
9
            name: 姓名
10
            age: 年龄
11
        """
12
        self.name = name
13
        self.age = age
14

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

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

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

运行结果预期:

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

练习题#

• 1. 单行注释练习 创建文件 test_comment.py，完成以下操作：

  • 写一行注释说明程序功能
  • 写一个 print 语句输出 “Hello”
  • 再写一行注释

  参考答案：

  1
  # 这是我的第一个 Python 程序
  2
  print("Hello")
  3
  # 程序结束

• 2. 多行注释练习 创建文件 test_multiline.py，用三种方式写注释：

  • 用 # 写三行单行注释
  • 用 ''' 写多行注释
  • 用 """ 写多行注释

  参考答案：

  1
  # 第一行注释
  2
  # 第二行注释
  3
  # 第三行注释
  4
  
  5
  '''
  6
  这是多行注释
  7
  用三个单引号
  8
  '''
  9
  
  10
  """
  11
  这是多行注释
  12
  用三个双引号
  13
  """
  14
  
  15
  print("注释练习完成")

  显示更多显示更少

• 3. Docstring 练习 创建文件 test_docstring.py，完成以下操作：

  • 写一个函数 greet(name)，功能是返回 "你好，{name}！"
  • 给函数添加 Docstring 说明
  • 用 print(函数名.__doc__) 打印文档

  参考答案：

  1
  def greet(name):
  2
      """返回问候语"""
  3
      return f"你好，{name}！"
  4
  
  5
  print(greet.__doc__)
  6
  print(greet("小明"))

• 4. 注释嵌套练习 创建文件 test_nest.py，完成以下操作：

  • 写一个多行注释 ''''''
  • 在多行注释内部用 # 写单行注释
  • 观察是否能正常运行

  参考答案：

  1
  '''
  2
  这是外部的多行注释
  3
  # 这是内部的单行注释
  4
  # 可以嵌套在多行注释中
  5
  '''
  6
  print("嵌套注释练习完成")

• 5. 带 Docstring 的函数 创建文件 test_func_doc.py，完成以下操作：

  • 写一个函数 add(a, b)，返回两数之和
  • 添加详细的多行 Docstring，说明参数和返回值
  • 用 help() 查看文档

  参考答案：

  1
  def add(a, b):
  2
      """
  3
      计算两数之和
  4
  
  5
      参数:
  6
          a: 第一个数字
  7
          b: 第二个数字
  8
  
  9
      返回:
  10
          两数之和
  11
      """
  12
      return a + b
  13
  
  14
  help(add)