Python多行注释怎么写？

大家好，今天本人给大家带来文章《Python多行注释怎么写？》，文中内容主要涉及到，如果你对文章方面的知识点感兴趣，那就请各位朋友继续看下去吧~希望能真正帮到你们，谢谢！

Python中实现多行注释主要靠三重引号字符串或连续#号。三重引号字符串未赋值时被忽略，常用于临时注释或文档说明，但仅当位于模块、类、函数开头时才被视为Docstring，成为可编程访问的__doc__属性；而普通多行注释应使用#，适合禁用代码或添加旁注。选择策略：对外接口用Docstring，调试用#，内部解释倾向#以避免混淆。最佳实践强调注释“为什么”而非“是什么”，保持同步更新，遵循PEP 8风格，提升代码可读性与维护性。

Python中并没有一个官方定义的多行注释语法，我们通常通过两种方式来实现类似多行注释的效果：一种是利用三重引号字符串（无论是单引号还是双引号），如果这个字符串没有被赋值给任何变量，它就会被解释器忽略，从而起到注释的作用；另一种则是简单粗暴地在每一行前面都加上井号#。这两种方法各有其适用场景和“潜规则”，理解它们背后的逻辑，能帮助我们写出更清晰、更易维护的代码。

解决方案

在Python中处理多行注释，主要有两种被广泛接受且实践有效的方法。

首先，最常见也最“Pythonic”的做法是使用三重引号字符串。无论是"""你的多行内容"""还是'''你的多行内容'''，只要这段字符串没有被赋值给任何变量，也没有作为docstring（文档字符串）出现在模块、类或函数的开头，Python解释器在运行时会将其视为一个未使用的字符串字面量，并直接忽略它。这使得它在效果上等同于多行注释。这种方式的好处是，你可以非常方便地注释掉一大段文本或者代码块，而且看起来也比较整洁。

"""
这是一个使用三重双引号的
多行“注释”。
它可以用来暂时禁用一段代码，
或者只是写一些较长的说明文字。
print("这行代码不会执行")
"""

'''
也可以使用三重单引号，效果是一样的。
通常，我们会根据项目的PEP 8规范或者个人习惯来选择。
例如，如果字符串内部包含双引号，外部就用单引号包围。
'''
# print("这行代码会执行")

其次，更直接但可能略显“笨拙”的方法是多行连续的单行注释。顾名思义，就是在你需要注释的每一行代码或文本前面都加上一个井号#。这种方法在需要注释掉几行代码，或者在代码块内部添加多行解释时非常实用。现代IDE（如VS Code、PyCharm）通常提供了快捷键（比如Ctrl + / 或 Cmd + /）来快速选中多行并批量添加或移除#，这大大提升了效率。

# 这是一行注释
# 这是另一行注释
# 这种方式在注释掉一小段代码时很方便
# def my_function():
#     print("这段代码被注释掉了")
#     pass

Python中，Docstring和普通多行注释到底有何本质区别？

在我看来，这是很多初学者，甚至一些有经验的开发者都容易混淆的地方。表面上看，Docstring（文档字符串）和我们刚才提到的用三重引号实现的“多行注释”都是用"""..."""或'''...'''包裹起来的，但它们在Python世界里的地位和用途是截然不同的。

Docstring的本质，在于它是一种元数据（metadata）。它不仅仅是给人看的注释，更是Python对象（模块、类、函数）自身的一部分。当你把三重引号字符串放在模块的开头、类定义的紧下方、或者函数定义的紧下方时，Python解释器会特别对待它，将其作为该对象的__doc__属性存储起来。这意味着你可以通过程序来访问这些文档，比如调用help(my_function)，或者直接访问my_function.__doc__，就能看到这些文档内容。它承担着官方文档的角色，是描述代码功能、参数、返回值、异常等重要信息的标准方式。它是有结构、有意义的，并且被各种自动化工具（如Sphinx文档生成器、IDE的智能提示）所利用。

而我们用三重引号实现的“普通多行注释”，如果它没有被放置在上述的特定位置，或者被赋值给一个变量，那么它就仅仅是一个未使用的字符串字面量。Python解释器会解析它，但发现它没有任何作用（既不是表达式的结果，也不是docstring），就会直接丢弃。它不会被存储到任何__doc__属性中，也无法通过程序访问。它的唯一作用就是让代码块在视觉上被“注释掉”，或者提供一些开发时的临时笔记。它不具备Docstring的语义和可访问性。

所以，核心区别在于：Docstring是有生命周期、有意义、可编程访问的文档，是代码契约的一部分；而“普通多行注释”则只是临时的、无语义、不可编程访问的文本块，更接近于开发者给自己或同事留下的便签。

Python开发中，我该如何选择最合适的“多行注释”策略？

选择哪种“多行注释”策略，其实很大程度上取决于你的目的和上下文。这没有绝对的对错，更多的是一种权衡和习惯。

如果你是为了提供代码的官方文档，比如解释一个模块的用途、一个类的职责、一个函数的输入输出和行为，那么毫无疑问，你必须使用Docstring。这是Python社区的黄金标准，它能让你的代码更易于理解、维护，并且能被自动化工具利用。一个好的Docstring可以极大地减少其他注释的需求，因为它已经把最核心的信息表达清楚了。我个人在编写任何公共API（函数、类、模块）时，都会优先考虑编写清晰、符合PEP 257规范的Docstring。

如果你只是想临时禁用一段代码，或者在开发过程中测试不同的实现，那么使用多行连续的单行注释（#）是最好的选择。它的意图非常明确——“这段代码暂时不运行”。而且，现代IDE的快捷键让这种操作变得异常高效。我经常在调试时用它来快速隔离问题代码，或者在重构时逐步替换旧逻辑。这种方式避免了三重引号字符串可能带来的语义混淆（它到底是不是Docstring？），也避免了不必要的内存开销（尽管很小）。

如果你想在代码块内部添加一段较长的、非文档性的解释，例如解释一段复杂算法的数学原理，或者某个特定实现背后的设计决策，那么我个人更倾向于使用多行连续的单行注释。虽然三重引号字符串也能做到，但我总觉得它在代码块中间出现，会有点“抢戏”，让人误以为是Docstring。用#开头，清晰地表明它只是一个“旁注”，不会被误解。

总结一下我的选择逻辑：

• 对外接口（模块、类、函数）： 强制使用Docstring。
• 临时禁用代码/调试： 优先使用#批量注释。
• 代码内部长篇解释： 倾向于使用#多行注释。
• 避免： 除非是Docstring，否则尽量少用三重引号字符串作为普通注释，以防混淆。

除了语法，Python注释还有哪些值得注意的“潜规则”或最佳实践？

除了如何写，什么时候写、写什么，以及怎么维护，才是Python注释真正的“潜规则”和最佳实践。这不仅仅是技术问题，更关乎代码的可读性、可维护性和团队协作。

一个核心原则是：代码应该是自解释的。这意味着我们应该努力通过清晰的变量名、函数名、类名以及良好的代码结构来表达意图，而不是过度依赖注释。如果一段代码需要大量的注释才能理解，那往往说明代码本身不够好。注释应该是代码的补充，而不是替代品。

那么，注释应该写什么呢？在我看来，注释的价值在于解释“为什么”，而不是“是什么”。

• 解释非显而易见的逻辑： 如果一段代码的实现方式不直观，或者包含了一些“魔术数字”或特殊优化，注释就应该解释这些选择背后的原因。
• 解释业务逻辑或设计决策： 为什么选择这种算法而不是另一种？为什么这里要处理一个看似多余的边界条件？这些是代码本身无法直接表达的。
• 警示潜在问题或副作用： 比如某个函数调用可能会很慢，或者某个参数的修改会影响其他模块。
• TODO/FIXME标记： 这是一种特殊的注释，用来标记待办事项或已知问题，方便未来跟踪。

另外，保持注释的及时更新至关重要。过时的注释比没有注释更糟糕，因为它会误导读者。每当修改代码时，都要检查相关的注释是否仍然准确。这听起来简单，但在实际开发中却常常被忽视，导致代码和注释“脱节”。

最后，遵循PEP 8的注释风格指南。例如，#后面要有一个空格，注释行不应超过79个字符（尽管现在屏幕大了，这个限制有时会放宽，但保持简洁总没错）。对于Docstring，PEP 257有更详细的规范，包括如何描述参数、返回值、异常等。团队内部也应该约定一套统一的注释风格，这对于协作和代码审查非常有益。

在我个人的经验中，一个好的注释系统是代码质量的体现。它不是用来掩盖烂代码的，而是用来提升好代码的理解深度和维护效率的。注释就像是一本代码的“幕后故事”，它揭示了代码表面之下那些不为人知的智慧和思考。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Python多行注释怎么写？》文章吧，也可关注golang学习网公众号了解相关技术文章。