Python代码注释的一些基础知识

在编写Python代码时，确保您的代码易于被其他人理解是很重要的。给变量、函数起合适的名字以及合理地组织代码都是很好的方法。

使用注释是增加代码可读性的另一个方便简单且重要的方法！

我们将介绍编写Python注释的一些基础知识。您将学习如何优雅地编写干净、简洁的注释，以及了解何时您可能根本不需要编写任何注释。

为什么注释代码如此重要

注释是任何程序的一个组成部分，它们可以以注释块的形式或者在代码行中出现，来帮助阐明解释一个复杂的函数。

在深入研究不同类型的注释之前，让我们仔细看看为什么代码注释如此重要。

假设在以下两种情况中，程序员不对代码进行注释。

当阅读你自己的代码时

客户端A希望在最后一刻部署他们的Web服务，截止日期就快到了，所以你决定先把它整体先做好，所有“额外”的东西如文档、适当的注释等等之后再添加。

最终，在最后期限时，及时地部署了Web服务。

但当你还没来及进行添加注释时，你就迎来了老板要求马上开始的新项目，在进行新项目的同时，你可能会把客户A的代码注释忘得一干二净。

六个月后，客户A需要为相同的服务构建一个补丁来满足一些新的需求。维护它是你的工作，因为你是第一个建造它的人。打开文本编辑器后……

“我之前到底写了什么？！”

你花了几个小时分析你的旧代码，但你完全迷失在混乱中。您当时非常匆忙，没有正确命名变量，甚至没有在适当的控制流中设置函数。最糟糕的是，脚本中没有任何注释来告诉您什么是什么！

开发人员总是忘记他们自己的代码所做的事情，尤其是如果代码是在很久以前编写的，或者是在很大的压力下编写的。当最后期限快到了，在电脑前几个小时导致眼睛充血时，这种压力可以用比平时更混乱的代码形式反映出来。

一旦提交了项目，许多开发人员就会因太累了，根本无法回过头来注释他们的代码。当到了之后重新来用它的时候，可能要花上几个小时来分析自己所写的东西。

边写代码边写注释是防止上述情况发生的一个很好的方法，请善待未来的你！

当别人在阅读你的代码时

假设你是从事一个小型Django项目的唯一开发人员，感觉自己很好地理解了自己的代码，所以你不倾向于花费更多的时间来编写注释或任何其他说明文档。

可能到年底，你的“小Django项目”已经变成了一个“20000行代码”的项目，而您的主管正在安排更多的开发人员来帮助维护它。

新的开发人员努力工作，以迅速投入进来，但在合作的头几天，你便会意识到他们会遇到一些麻烦。在项目代码中，你使用了一些奇怪的变量名，并使用超级简洁的语法编写。这就导致新员工会花费大量的时间逐行遍历您的代码，以试图弄清楚它是如何工作的。

在这种情况下，在代码中使用注释可以很好地帮助其他开发人员读懂你的代码，你可以通过从项目一开始就对代码进行注释来帮助与其他开发人员的合作。

如何用Python编写注释

现在我们已经知道了为什么代码注释如此重要，那么让我们来看一些有关注释的基本知识，以便熟悉如何正确地使用它。

Python注释基础

要用Python编写注释，只需将“#”放在您的注释内容之前：

Python会忽略在#标记之后到行尾的所有内容，您可以在代码中的任何位置插入它们，甚至可以在代码行中使用：

当你运行上述代码时，你只会看到This will run的输出，其他的都会被忽略。

评论应该简短、贴切、切中要害。PEP 8建议将代码保持在79个字符或更少，代码行中的注释最多为72个字符。如果您的注释接近或超过了该长度，则需要将其转变为多行注释。

Python多行注释

不幸的是，Python无法像用C、Java和Go语言那样编写多行注释：

在上述示例中，程序将忽略第一行，但其他行将引发语法错误。

相反，像Java这样的语言可以很容易地将注释扩展到多行：

程序会自动忽略/和/之间的所有内容。

虽然Python没有这种多行注释功能，但可以在Python中创建多行注释，主要有一下两种简单的方法。

第一种方法是在每一行后面简单地按下回车键，添加一个新的#标记，然后继续注释：

程序将忽略以#标记开头的每一行。

另一种方法是使用多行字符串将注释包装在一组三引号中：

这与Java中的多行注释类似，在Java中，包含在三元引号中的所有内容都将成为注释。

虽然这貌似提供了多行注释功能，但从技术上讲，这并不是一个注释。它仅仅是一个没有分配给任何变量的字符串，所以程序不会调用或引用它。不过，由于它在运行时会被忽略并且不会出现在字节码中，所以它可以有效地充当注释。

但是，在放置这些多行“注释”时要小心。根据它们在程序中的位置，它们有时可以转换为docstring，这是与函数或方法相关联的文档片段。如果您在函数定义之后将这些“注释”放进去，那么想要成为注释的内容将与该对象相关联。在使用这种多行注释时要小心，如果有疑问，保险起见在后面的每一行上添加一个#标记即可。

Python注释快捷键

每次需要添加注释时，都要键入#标记可能会很繁琐。那么，我们能做些什么来加快速度呢？这里有一些技巧可以帮助你更快地添加注释。

第一就是使用多个游标，就是通过在屏幕上放置多个光标来完成任务。左键单击时，只需按住ctrl或cmd键，就会看到屏幕上闪烁的线条：

当需要在多个地方对相同的事情进行注释时，这是最有效的。

如果我们有很长一段文字需要注释呢？或者批量将代码转化为注释，一行一行地注释它可能需要很多时间！在这种情况下，只需选择需要作为注释的代码行并在PC上按Ctrl+/，或在Mac上按Cmd+/：

所有选中的代码前都将加上一个#标记，并被程序忽略。

如果注释行数较多，或者正在阅读的脚本中的注释非常长，那么您的文本编辑器可能会让您选择使用左侧的小箭头折叠它们：

只需单击箭头以隐藏注释即可。如果长注释分散在多行，或占用程序大部分启动时间的docstring中，这种方法效果最好。

将这些技巧结合在一起，将使您的代码注释快速、简单。

Python注释最佳实践

知道如何用Python编写注释相当重要，但同样重要的是要确保注释具有可读性和易懂性。

以下技巧，可以帮助您编写真正适合您的代码的注释。

为自己编写代码时

通过正确地注释自己的代码，可以让自己的程序员生活更轻松。即使没有其他人会看到它，但你之后可能会反复看它，这是你为它添加注释的足够的理由。毕竟，您是一个开发人员，应该让您的代码容易理解。

为自己编写注释的一个非常有用的技巧是将其作为代码的大纲。如果不确定你的程序将如何发展，那么您可以使用注释来跟踪剩余的工作，甚至可以作为跟踪高级程序流的一种方法。例如，使用注释来勾勒伪代码中的函数：

这些注释计划出了get_top_cies，说明你准确地知道了你想要你的函数做什么，后面可以很方便地将它翻译成代码。

使用这样的注释可以帮助你保持头脑清醒。当遍历你的程序时，将知道要获得一个功能齐全的脚本，还需要做些什么。在将注释“转换”成代码之后，请记住删除任何已经变得多余的注释，这样您的代码就可以保持清晰和干净。

还可以使用注释作为调试过程的一部分。注释掉旧代码，看看它如何影响您的输出。如果感觉输出符合要求，那么就可以去掉程序中注释掉的代码，以提高代码的可读性。您也可以使用程序版本控制，方便后面旧代码的找回。

最后，使用注释来定义自己代码的棘手部分。如果你放下一个项目，几个月或几年后再回到它，你将需要花费大量的时间来重新熟悉你所写的东西。为以防万一你忘记自己的代码做了什么，帮未来你一个忙，为其添加注释，这样以后就更容易更快速的重新读懂它。

为他人编写代码时

人们喜欢在阅读文本信息时跳来跳去，而阅读代码也是如此。当代码出了问题您必须弄清楚到底发生了什么错误时，您才可能会逐行阅读代码。

在大多数其他情况下，您将快速浏览变量和函数定义，以获得要点。用简单的注释解释正在发生的事情，能真正帮助开发人员了解在这个位置上做些什么。

请善待你的同事，用注释来帮助他们浏览你的代码。如果您有一个名称不易理解的复杂方法或函数，您可能需要在def行后面添加一个简短的注释，以说明问题：

这可以帮助正在浏览你的代码的其他开发人员了解该函数的功能。

对于任何公共函数，我们都希望尽量包含一个关联的docstring，不管它是否复杂：

此字符串将成为函数的.doc属性，并将正式与该特定方法相关联。

PEP 257指南有多行docstring的约定。这些文档字符串出现在文件的顶部，包括对整个脚本以及它应该做什么的高级概述：

像这样的模块级文档字符串将包含任何相关或需要知道的信息，供开发人员阅读。在编写一个函数时，建议列出所有的类、异常和函数，以及每个类的一行摘要。 Python注释最糟实践

正如编写Python注释有好的标准一样，有几种类型的注释要尽量避免。下面是一些例子。

避免：W.E.T.注释

你的注释应该是D.R.Y，这是“Don’t Repeat Yourself.”的缩写，意味着你的代码注释应该很少或没有冗余。您不需要对一段足以解释自身的代码进行注释，如下所示：

我们可以清楚地看到，a是返回值，因此没有必要在注释中特别地声明这一点。这就是W.E.T.注释，意思是“wrote everything twice”，也可以理解为“wasted everyone’s time”。

W.E.T.注释可能是一个简单的错误，特别是如果在编写代码之前使用注释来规划代码。但是，一旦代码运行良好，一定要返回来删除不必要的注释。

避免：利用注释来弥补代码

注释有时会反映出您的代码可能存在深层次的问题，注释是试图隐藏代码自身问题的一种方法，但注释应该支持你的代码，而不是试图弥补它。如果您的代码编写得很糟糕，那么任何注释都不会修复它。

让我们以这个简单的例子为例：

这段代码很不规范，在解释代码的每一行之前都有一个注释。通过为变量、函数和集合指定合理的名称，这个脚本可以变得更简单，如下所示：

通过使用易于理解的命名方式，我们能够删除所有不必要的注释，并减少代码的长度！

注释一般要比它们支持的代码短很多，如果你花了太多时间解释您所做的事情，那么你需要返回并重构，以使你的代码更加清晰和简洁。

避免：粗鲁的注释

这是在开发团队工作时可能会出现的问题。当几个人都在处理相同的代码时，其他人可能会检查你所写的内容并进行更改。有时，你可能会遇到一个敢于写这样的评论的人：

这种行为是极其不好的，如果不小心把这条注释留在了那里，然后一个客户看到了它，这样会很尴尬。你是一个专业人士，在你的注释中加入粗俗的话会有辱自己的身份。

结语

学会优雅地使用注释是很有价值的，您不仅学习了如何将其编写得更清楚、更简洁，而且无疑你也会对Python有更深入的了解。

知道如何用Python注释可以使所有开发人员(包括您自己)的编程生活变得更轻松！它们可以帮助其他开发人员快速了解您的代码，并帮助您重新熟悉自己的旧代码。

注意，当使用注释尝试解释或弥补编写不良的代码时，返回并修改你的代码是更好的选择。注释以前编写的代码，无论是你自己的代码还是其他开发人员的代码，都是练习用Python编写注释的好方法。