Python - 注释


Python 注释是 Python 源代码中程序员可读的解释或注释。添加它们的目的是使源代码更易于人类理解,并且被 Python 解释器忽略。注释增强了代码的可读性,并帮助程序员非常仔细地理解代码。

示例

如果我们执行下面给出的代码,生成输出将简单地将 “Hello, World!” 打印到控制台,因为 Python 解释器会忽略注释,不会影响程序的执行 -


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

Python 支持三种类型的注释,如下所示 -

  • 单行注释
  • 多行注释
  • 文档字符串注释

Python 单行注释

Python 单行注释以井号 (#) 开头,并延伸到行尾。用于提供有关代码的简短说明或注释。可以放置在描述代码上方的单独行上,也可以放在代码行的末尾(称为内联注释),以提供有关该特定行的上下文或说明。

示例:独立单行注释

独立单行注释是单独占据一整行的注释,以哈希符号 (#) 开头,位于它描述或注释的代码之上。

在此示例中,独立的单行注释位于“greet”函数“−


# 此处放置独立的单行注释
def greet():
	 	print("Hello, World!")
greet()

示例:内联单行注释

内联单行注释是与一段代码出现在同一行的注释,位于代码后面,前面带有哈希符号 (#)。

在这里,内联单行注释遵循 print("Hello, World") 语句 -


print("Hello, World!") 	# 内联单行注释放在这里

Python 多行注释

Python 多行注释用于提供跨多行的较长解释或注释。虽然 Python 没有用于多行注释的特定语法,但有两种常见的方法可以实现此目的:连续的单行注释和三引号字符串 -

连续单行注释

连续单行注释是指在每行开头使用井号 (#)。此方法通常用于较长的解释或分割代码的某些部分。

在此示例中,使用多行注释来解释阶乘函数的用途和逻辑 -


# 此函数计算一个数字的阶乘
# 使用迭代方法。一个数的阶乘
# n是小于或等于的所有正整数的乘积
# 例如,阶乘(5)为5*4*3*2*1=120。
def factorial(n):
	 	if n < 0:
	 	 	 return "负数未定义阶乘"
	 	result = 1
	 	for i in range(1, n + 1):
	 	 	 result *= i
	 	return result

number = 5
print(f" {number} 的阶乘是 {factorial(number)}")

三引号字符串多行注释

我们可以使用三引号字符串(''' 或 “”“) 来创建多行注释。这些字符串在技术上是字符串文本,但如果它们未分配给任何变量或在表达式中使用,则可以用作注释。

此模式通常用于块注释或记录需要详细说明的代码部分。

在这里,三引号字符串提供了 “gcd” 函数的详细说明,描述了其用途和使用的算法 -


"""
此函数计算最大公约数(GCD)
使用欧几里德算法计算两个数字。GCD
两个数字是将它们分开的最大数字
不留余物。
"""
def gcd(a, b):
	 	while b:
	 	 	 a, b = b, a % b
	 	return a

result = gcd(48, 18)
print("48和18的最大公约数(GCD)是:", result)

文档注释

Python 文档注释(也称为文档字符串)提供了一种将文档合并到代码中的方法。这对于解释模块、类、函数和方法的用途和用法非常有用。有效使用文档注释有助于其他开发人员理解您的代码及其用途,而无需阅读实现的所有详细信息。

Python 文档字符串

Python 文档字符串是一种特殊类型的注释,用于记录模块、类、函数和方法。它们使用三引号(''' 或 “”“)编写,并紧跟在它们记录的实体的定义之后。

文档字符串可以通过编程方式访问,这使它们成为 Python 内置文档工具不可或缺的一部分。

函数 Docstring 示例


def greet(name):
	 	"""
	 	此函数用于问候姓名作为参数传递的人。

	 	参数:
	 	name(str):要问候的人的名字

	 	返回值:
	 	None
	 	"""
	 	print(f"Hello, {name}!")
greet("Alice")

访问文档字符串

可以使用 .__doc__ 属性或 help() 函数访问文档字符串。这样,您可以直接从交互式 Python shell 或在代码轻松查看任何模块、类、函数或方法的文档。

示例:使用 .__doc__ 属性


def greet(name):
	 	 """
	 	 此函数用于问候姓名作为参数传递的人。

	 	 参数:
	 	 name (str): 要问候的人的名字

	 	 返回值:
	 	 None
	 	 """
print(greet.__doc__)

示例:使用 help() 函数


def greet(name):
	 	 """
	 	 此函数用于问候姓名作为参数传递的人。

	 	 参数:
	 	 name (str): 要问候的人的名字

	 	 返回值:
	 	 None
	 	 """
help(greet)