以正确的方式创建 Python 注释

注释是程序员添加到他们的代码中以解释该代码应该做什么的注释。 将代码转化为动作的编译器或解释器会忽略注释，但它们对于管理软件项目可能是必不可少的。

注释有助于向其他程序员解释您的 Python 代码，并且可以提醒您做出这些选择的原因。 注释通过帮助未来的程序员理解软件背后的设计选择，使调试和修改代码变得更加容易。

尽管注释主要是针对开发人员的，但编写有效的注释也有助于为您的代码用户生成出色的文档。 借助 Sphinx for Python 项目等文档生成器，代码中的注释可以为文档提供内容。

让我们深入了解 Python 中的注释。

Python 中的注释

根据 Python PEP 8 Style Guide，在编写注释时需要注意以下几点：

• 评论应始终是完整而简洁的句子。
• 与其发表难以理解或不准确的评论，不如完全没有评论。
• 注释应定期更新以反映代码中的更改。
• 过多的注释会分散注意力并降低代码质量。 在代码的目的很明显的地方不需要注释。

在 Python 中，以#符号开头的行被声明为注释。 当 Python 解释器在您的代码中遇到#时，它会忽略该符号之后的任何内容并且不会产生任何错误。 声明单行注释有两种方式：行内注释和块注释。

行内评论

行内注释提供变量和简单操作的简短描述，与代码语句写在同一行：

 border = x + 10 # Make offset of 10px

注释在与代码相同的语句中说明代码的作用。

阻止评论

块注释用于描述代码中的复杂逻辑。 Python 中的块注释的构造类似于内联注释——唯一的区别是块注释写在单独的一行上：

 import csv from itertools import groupby # Get a list of names in a sequence from the csv file with open('new-top-firstNames.csv') as f: file_csv = csv.reader(f) # Skip the header part: (sr, name, perc) header = next(file_csv) # Only name from (number, name, perc) persons = [ x[1] for x in file_csv] # Sort the list by first letter because # The groupby function looks for sequential data. persons.sort(key=lambda x:x[0]) data = groupby(persons, key=lambda x:x[0]) # Get every name as a list data_grouped = {} for k, v in data: # Get data in the form # {'A' : ["Anthony", "Alex"], "B" : ["Benjamin"]} data_grouped[k] = list(v)

请注意，在使用块注释时，注释写在它们正在解释的代码之上。 Python PEP8 Style Guide 规定一行代码不应超过七十九个字符，内联注释通常会超过这个长度。 这就是为什么编写块注释以在单独的行中描述代码的原因。

多行注释

Python 本身不支持多行注释，这意味着没有专门的规定来定义它们。 尽管如此，经常使用跨越多行的注释。

您可以通过在每行前面加上#来从几个单行注释中创建一个多行注释：

 # interpreter # ignores # these lines

您还可以使用多行字符串语法。 在 Python 中，您可以通过将字符串括在"""三重双引号或'''三重单引号中来定义多行字符串：

 print("Multi-Line Comment") """ This String is Multi line """

在上面的代码中，多行字符串没有分配给变量，这使得字符串像注释一样工作。 在运行时，Python 会忽略该字符串，并且它不会包含在字节码中。 执行上面的代码会产生以下输出：

 Multi-Line Comment

特别评论

除了使您的代码可读之外，注释在 Python 中也有一些特殊用途，例如规划未来的代码添加和生成文档。

Python 文档字符串注释

在 Python 中，文档字符串是解释如何使用给定函数或类的多行注释。 通过创建高质量的文档字符串来改进代码的文档。 在使用函数或类并使用内置的help(obj)函数时，文档字符串可能有助于提供对象的概述。

Python PEP 257 提供了在 Python 中声明文档字符串的标准方法，如下所示：

 from collections import namedtuple Person = namedtuple('Person', ['name', 'age']) def get_person(name, age, d=False): """ Returns a namedtuple("name", "age") object. Also returns dict('name', 'age') if arg `d` is True Arguments: name – first name, must be string age – age of person, must be int d – to return Person as `dict` (default=False) """ p = Person(name, age) if d: return p._asdict() return p

在上面的代码中，文档字符串提供了有关关联函数如何工作的详细信息。 使用 Sphinx 等文档生成器，此文档字符串可用于向您的项目用户提供有关如何使用此方法的概述。

也可以使用内置的help()函数返回在函数或类签名下方定义的文档字符串。 help()函数将对象或函数名称作为参数，并返回函数的文档字符串作为输出。 在上面的示例中，可以调用help(get_person)来显示与get_person函数关联的文档字符串。 如果您使用-i标志在交互式 shell 中运行上面的代码，您可以看到 Python 将如何解析此文档字符串。 通过键入python -i file.py运行上面的代码。

help(get_person)函数调用为您的函数返回一个文档字符串。 输出包含get_person(name, age, d=False) ，这是 Python 自动添加的函数签名。

get_person.__ doc__属性也可用于以编程方式检索和修改文档字符串。 在上面的示例中添加“Some more new information”之后，它出现在对help(get_person)的第二次调用中。 不过，您不太可能需要像这样在运行时动态更改文档字符串。

TODO 评论

编写代码时，有时您会想要突出显示某些行或整个块以进行改进。 这些任务由 TODO 注释标记。 当您计划更新或更改代码时，或者如果您希望通知项目的用户或合作者文件代码的特定部分仍有待编写，TODO 注释会派上用场。

TODO 注释不应该写成伪代码——它们只需要简要解释尚未编写的代码的功能。

TODO 注释和单行块注释非常相似，它们之间的唯一区别是 TODO 注释必须以 TODO 前缀开头：

 # TODO Get serialized data from the CSV file # TODO Perform calculations on the data # TODO Return to the user

重要的是要注意，尽管许多 IDE 可以为程序员突出显示这些注释，但 Python 解释器对 TODO 注释的看法与块注释没有任何不同。

编写 Python 注释的最佳实践

在撰写评论以确保可靠性和质量时，应遵循许多最佳实践。 以下是使用 Python 编写高质量评论的一些技巧。

避免明显的

陈述显而易见的注释不会为您的代码增加任何价值，应该避免。 例如：

 x = x + 4 # increase x by 4

该注释没有用，因为它只是说明了代码的作用，而没有解释为什么需要这样做。 注释应该解释它们所描述的代码的“原因”而不是“什么”。

重写后更有用，上面的示例可能如下所示：

 x = x + 4 # increase the border width

保持 Python 注释短小精悍

保持您的评论简短易懂。 它们应该用标准的散文而不是伪代码编写，并且应该取代阅读实际代码以大致了解其功能的需要。 过多的细节或复杂的注释不会使程序员的工作变得更轻松。 例如：

# return area by performing, Area of cylinder = (2*PI*r*h) + (2*PI*r*r) def get_area(r,h): return (2*3.14*r*h) + (2*3.14*r*r)

上面的评论提供了比读者所需更多的信息。 注释不应指定核心逻辑，而应提供代码的一般摘要。 这条评论可以改写为：

 # return area of cylinder def get_area(r,h): return (2*3.14*r*h) + (2*3.14*r*r)

谨慎使用标识符

在注释中应谨慎使用标识符。 更改标识符名称或大小写会使读者感到困惑。 例子：

 # return class() after modifying argument def func(cls, arg): return cls(arg+5)

上面的评论提到了class和argument ，这两个都没有在代码中找到。 这条评论可以改写为：

 # return cls() after modifying arg def func(cls, arg): return cls(arg+5)

干湿

当您编写代码时，您要坚持 DRY（不要重复自己）原则并避免 WET（所有内容都写两次）。

评论也是如此。 避免使用多个语句来描述您的代码，并尝试将解释相同代码的注释合并为一个注释。 但是，在合并评论时一定要小心：粗心地合并多个评论可能会导致违反风格指南的巨大评论，并且读者难以理解。

请记住，注释应该减少代码的阅读时间。

 # function to do x work def do_something(y): # x work cannot be done if y is greater than max_limit if y < 400: print('doing x work')

在上面的代码中，评论被不必要地分散了，可以合并成一个评论：

 # function to do x if arg:y is less than max_limit def do_something(y): if y in range(400): print('doing x work')

一致的缩进

确保注释的缩进水平与其所描述的代码相同。 如果不是，则很难遵循。

例如，这条评论没有缩进或定位不当：

 for i in range(2,20, 2): # only even numbers if verify(i): # i should be verified by verify() perform(x)

可以改写如下：

 # only even numbers for i in range(2,20, 2): # i should be verified by verify() if verify(i): perform(x)

概括

注释是编写可理解代码的重要组成部分。 您在撰写评论方面所做的投资是您未来的自己——或其他需要在您的代码库上工作的开发人员——会感激的。 注释还可以让您更深入地了解您的代码。

在本教程中，您了解了有关 Python 注释的更多信息，包括各种类型的 Python 注释、何时使用每种注释以及创建它们时应遵循的最佳实践。

写出好的评论是一项需要学习和发展的技能。 要练习撰写评论，请考虑返回并为您以前的一些项目添加评论。 如需灵感并查看最佳实践，请查看 GitHub 上文档齐全的 Python 项目。

当您准备好让自己的 Python 项目上线时，Kinsta 的应用程序托管平台可以在几秒钟内将您的代码从 GitHub 传输到云端。