在 Python 中添加注释

介绍

在这个 Lab 中，你将学习 Python 中注释（comments）的重要性及其实际应用。注释对于使你的代码易于理解至关重要，这对代码维护和协作至关重要。你将探索不同类型的注释，包括单行注释和多行注释，并学习如何有效地使用它们来提高代码的可读性。

理解注释的目的

注释是你代码中的注解，它们会被 Python 解释器忽略，但对人类读者来说非常有价值。它们有助于解释代码的逻辑、目的以及任何不明显的细节。虽然机器执行代码，但阅读和维护代码的是人类。良好的注释习惯对于编写清晰易懂的程序至关重要。

让我们从一个没有任何注释的简单脚本开始。在 WebIDE 中，找到左侧面板文件浏览器中的文件 purpose.py 并将其打开。

将以下代码添加到 purpose.py 文件中：

x = 10
y = 20
z = x + y
print(z)

按 Ctrl + S 保存文件。

要运行脚本，请通过导航到顶部菜单并选择 Terminal -> New Terminal 来打开 WebIDE 中的集成终端。终端将在屏幕底部打开，默认路径是 ~/project。

通过在终端中运行以下命令来执行脚本：

python purpose.py

你将看到计算结果的输出：

30

这个脚本很简单，但在一个更大的程序中，x、y 和 z 代表什么可能不那么清晰。在下一步中，我们将添加注释，使这段代码更容易理解。

使用单行注释

单行注释用于简短的解释性说明。在 Python 中，单行注释以井号（#）开头。解释器会忽略 # 之后该行中的所有内容。这些注释可以放在单独的一行来描述下面的代码，也可以放在与语句同一行来解释该语句。

让我们修改 purpose.py 文件以包含单行注释。在编辑器中打开 purpose.py 并将其内容更新为以下内容：

## This script calculates the sum of two numbers

x = 10  ## Assign the integer 10 to variable x
y = 20  ## Assign the integer 20 to variable y
z = x + y  ## Calculate the sum of x and y
print(z) ## Print the final result to the console

保存文件（Ctrl + S）并从终端再次运行它：

python purpose.py

输出将与之前相同：

30

如你所见，注释没有改变程序的行为。然而，代码现在可读性大大提高了。第一条注释解释了脚本的总体目的，而行内注释则阐明了每一行的作用。

使用多行注释

对于跨越多行的较长解释，你可以使用多行注释格式。尽管 Python 没有像某些其他语言那样的多行注释特定语法，但你可以为此目的使用多行字符串（multi-line strings）。

多行字符串是通过用三重引号（"""..."""（双引号）或 '''...'''（单引号））包围文本来创建的。如果这个多行字符串没有赋值给变量，Python 解释器会忽略它，从而有效地使其成为一个注释。这是一种编写块注释或函数文档（docstrings）的常见约定。

在 WebIDE 中找到并打开文件 multiline.py。添加以下代码：

"""
This is a multi-line comment using triple double quotes.
This script demonstrates how to write comments that span
several lines to provide more detailed explanations.
"""

message = "Hello, Python learners!"
print(message)

保存文件并从终端运行它：

python multiline.py

你将看到以下输出：

Hello, Python learners!

三重引号内的文本块被忽略了，只有 print 语句被执行了。这种技术对于在文件开头或复杂函数之前提供详细描述非常有用。

使用声明注释

Python 也支持被称为声明注释（declaration comments）的特殊注释。这些注释会被解释器或操作系统处理，以配置脚本的运行方式。两个常见的例子是 shebang 和编码声明。

1. Shebang (#!): Shebang 行是脚本的第一行。它告诉类 Unix 操作系统使用哪个解释器来执行该文件。对于 Python 3 脚本，这通常是 #!/usr/bin/python3。这允许你将脚本作为独立的可执行文件运行。

2. 编码声明（Encoding Declaration）: 此注释告诉 Python 解释器使用哪种字符编码来处理源文件。如果你的代码包含非 ASCII 字符，这一点很重要。UTF-8 的标准声明是 ## -*- coding: utf-8 -*-。它应该放在文件的第一行或第二行。

让我们创建一个同时使用这两种注释的脚本。在编辑器中打开文件 declaration.py 并添加以下代码：

#!/usr/bin/python3
## -*- coding: utf-8 -*-

## This script demonstrates declaration comments and non-ASCII characters.
print("Hello, World!")
print("你好，世界！") ## A greeting in Chinese

保存文件。在你可以直接运行此脚本之前，你需要使其可执行。在终端中，运行 chmod 命令：

chmod +x declaration.py

现在，你可以直接执行脚本，而无需先输入 python：

./declaration.py

输出将正确显示两行文本，包括中文字符：

Hello, World!
你好, 世界!

Shebang 行允许系统找到并使用 Python 3 解释器，而编码声明确保了非 ASCII 字符被正确处理。

总结

在这个实验（Lab）中，你学习了如何向 Python 代码添加注释。你练习了使用 # 进行单行注释以记录简短笔记，使用 """...""" 进行多行注释以提供更长的描述，以及使用 shebang 和编码声明等特殊声明注释来配置脚本执行。通过有效地注释你的代码，你使其更具可读性、可维护性，并更容易被他人（以及未来的你自己）理解。