理解Python中的代码注释
在编写任何编程语言的代码时，注释都是极其重要的组成部分。它们不是给计算机看的，而是留给人类读者——包括未来的你和你的团队成员——看的。注释用来解释代码的功能、逻辑、设计思路、甚至是临时的变通方法。
Python支持单行注释，即以井号（#）开头的那一行文本都会被解释器忽略。但这只适用于简单的行内说明。当需要注释一段较长的文本说明，或者临时禁用一个代码块时，单行注释就显得效率低下且不便了。这时，我们就需要“多行注释”的能力。
【python怎么注释多行代码】有哪些方法？ (What are the methods?)
Python并没有像C++或Java那样专门的/* ... */块注释语法。但开发者们通常使用两种主要的方法来实现类似多行注释的功能：
- 使用多个单行注释（
#）。 - 使用三引号字符串（
"""..."""或'''...'''）。
接下来，我们将详细探讨这两种方法及其背后的原理和适用场景。
方法一：使用多个单行注释 (#)
【python怎么注释多行代码】用多个#号是如何操作的？ (How to use multiple #?)
这是最直接、最符合“注释”本质的方法。你只需要在你想要注释的每一行代码或文本前加上一个井号（#）和一个空格（空格是惯例，非强制）。
如何操作：
将光标放在你想要注释的行的开头，键入#。如果要注释多行，就重复这个动作。
示例代码：
# 这是一段多行注释的示例。
# 我正在解释下面这段代码的复杂逻辑。
# 比如，这里涉及到用户输入处理和数据验证。
# 这是一种非常清晰的注释方式。【python怎么注释多行代码】用多个#号为什么普遍使用？ (Why is using multiple # common?)
- 清晰明了： 每一行都被明确标记为注释，阅读者一眼就能区分代码和注释。
- 编辑器支持： 几乎所有的Python集成开发环境（IDE）和代码编辑器都提供方便的快捷键（通常是选中代码块后按下
Ctrl + /或Cmd + /）来批量地为选中的多行代码添加或移除#前缀。这使得临时注释/取消注释一个代码块变得极其高效。 - 没有副作用： 这种方法纯粹是给解释器看的标记，告诉它忽略这些行。它不会创建任何字符串对象，也不会被误认为是文档字符串。
【python怎么注释多行代码】用多个#号可以用在哪些地方？ (Where can multiple # be used?)
- 临时禁用代码块： 在调试过程中，你可能需要暂时不执行某段代码，使用多行
#注释是最好的方式。通过编辑器快捷键，你可以轻松地注释掉一大块代码，测试其他部分，然后快速取消注释恢复原状。 - 解释复杂的代码段： 当一段代码逻辑比较复杂，需要多行文字来详细解释时，使用多行
#注释可以很好地组织这些说明。 - 文件顶部的信息： 比如版权声明、作者信息、文件创建日期等，如果不想使用文档字符串格式，可以用多行
#来表示。
【python怎么注释多行代码】用多个#号能注释多少行？ (How many lines can multiple # comment?)
理论上，使用多个#可以注释任意数量的连续行。只要每一行的开头都有#，解释器就会忽略它。
方法二：使用三引号字符串
【python怎么注释多行代码】用三引号是如何操作的？ (How to use triple quotes?)
Python中的字符串可以用单引号（'）、双引号（"）或三引号（''' 或 """）括起来。其中，三引号字符串可以跨越多行，并在其中包含换行符而不需要使用转义字符\n。
当一个三引号字符串出现在某个位置，但没有被赋值给一个变量，并且没有紧跟在模块、类、函数或方法定义的后面时，它实际上是一个字符串字面量。Python解释器会解析这个字符串，但因为它的值没有被使用，也没有特定的上下文使其成为文档字符串，所以它实际上起到了类似多行注释的作用。
如何操作：
将你想要“注释”的多行文本放在一对三双引号（"""）或一对三单引号（'''）之间。
示例代码 (作为非文档字符串使用)：
"""
这是一个使用三双引号作为“多行注释”的示例。
这里的文本可以跨越多行，非常方便书写。
注意：这种用法技术上是字符串，需了解其区别。'''
你也可以使用三单引号来达到同样的效果。
选择哪种取决于个人偏好或团队规范。
通常推荐与代码中使用的字符串引号类型一致。【python怎么注释多行代码】用三引号为什么有时用来做注释？ (Why are triple quotes sometimes used as comments?)
- 书写方便： 对于大段的说明性文字，只需要在开头和结尾各添加一对三引号，比在每一行前加
#要快。 - 视觉效果： 有人觉得这种块状的注释看起来比较整洁。
【python怎么注释多行代码】用三引号可以用在哪些地方？ (Where can triple quotes be used?)
- 文档字符串 (Docstrings)： 这是三引号字符串最主要和推荐的用途。紧跟在模块、类、方法或函数定义后的第一个表达式，如果是三引号字符串，就会被特殊处理为该对象的文档字符串，存储在
__doc__属性中，用于生成文档。这是官方推荐的Python代码文档化方式（遵循PEP 257规范）。 - 临时文本块： 在交互式环境或简单脚本中，可能用来快速输入一大段多行文本。
- 作为非官方的“注释”： 如前面所述，当它不作为文档字符串且未被赋值时，可以起到类似多行注释的作用。但这种用法不推荐用于临时禁用代码块，因为如果被注释的代码块内部包含与外层三引号匹配的引号，会导致语法错误。同时，它也容易与真正的文档字符串混淆。
【python怎么注释多行代码】用三引号能“注释”多少行？ (How many lines can triple quotes “comment”?)
一个三引号字符串可以包含任意数量的换行符，因此它可以“注释”任意数量的行。
【python怎么注释多行代码】使用三引号作为注释需要注意什么？ (What to be careful about when using triple quotes as comments?)
重要注意事项：文档字符串 vs. 伪注释
这是关于三引号最容易混淆的地方。
- 文档字符串 (Docstring)： 它们是官方的、用于代码文档化的工具。它们被解释器保留，可以通过
help()函数或文档生成工具访问。它们有特定的位置要求（必须是模块、类、函数或方法定义后的第一个表达式）和推荐的格式。- 用三引号实现的“多行注释”： 当三引号字符串不满足文档字符串的条件时，它们会被解释器处理（创建并立即丢弃），它们的值不会保留在任何地方（除了临时的栈帧）。它们不应该被视为官方的注释机制，其作用仅仅是因为它们是多行字符串字面量且其值未被使用。
强烈建议：
除非你是在编写文档字符串，否则不要依赖三引号字符串来注释代码块或写多行解释性文本。这样做容易引起以下问题：
- 混淆： 读者可能不清楚你的三引号是想做文档字符串还是普通注释。
- 潜在的副作用： 虽然值被丢弃，但解释器确实处理了它，理论上可能比完全忽略的
#行有微小的性能差异（虽然通常微不足道）。- 引号匹配问题： 如果你用三双引号
"""..."""去注释一段包含双引号字符串"..."的代码，可能会导致语法错误。使用多行#则不会有这个问题。因此，在绝大多数需要临时禁用代码或添加非文档性多行说明的场景下，使用多行
#注释是更安全、更清晰、更推荐的做法。
【python怎么注释多行代码】何时使用哪种方法？ (When to Use Which Method?)
- 需要临时注释掉一个代码块进行调试： 使用多行
#注释（配合编辑器快捷键）。这是最安全高效的方式。 - 需要为一段复杂的代码逻辑写大段解释性文字，且这些文字不是为了生成官方文档： 使用多行
#注释。保持注释和代码的界限清晰。 - 需要为模块、类、函数或方法编写官方文档： 必须使用三引号字符串作为文档字符串，并将其放在正确的位置，遵循PEP 257规范。
- 在交互式环境或非常简单的脚本中快速输入多行文本： 可以临时使用三引号字符串，但要清楚其本质不是传统的注释。
总结
尽管Python没有专门的“块注释”语法，但通过重复使用单行注释符（#）或利用三引号字符串（及其与文档字符串的区别），我们可以有效地实现多行注释的需求。
对于绝大多数场景下的多行代码注释或非文档性多行说明，强烈推荐使用多个单行注释（#）。 它的清晰性、编辑器支持以及避免与文档字符串混淆的优点，使其成为事实上的标准多行注释方法。
理解三引号字符串主要用于编写文档字符串，并避免将其作为通用的多行注释手段，是写出清晰、可维护Python代码的关键一步。
