Python 注释

目标

在本文章中，你将学习如何向代码添加注释。你将学习各种类型的Python注释，包括块注释、内联注释和文档字符串。

有时，你希望记录编写的代码。例如，你可能想要说明为什么一段代码可以工作。要做到这一点，可以使用注释。

通常，你可以使用注释来解释公式、算法和复杂的业务逻辑。

在执行程序时，Python解释器会忽略注释，只解释代码。

Python提供了三种注释，包括块注释、内联注释和文档字符串。

块注释解释它后面的代码。通常，你将代码块注释缩进到与代码块相同的级别。

要创建块注释，首先使用一个井号(#)，然后是一个空格和一个文本字符串。例如:

# 价格增加5%
price = price * 1.05

当你将注释放在语句的同一行时，你将拥有一个内联注释。

与块注释类似，内联注释以一个井号(#)开头，后面跟着一个空格和一个文本字符串。

下面的例子演示了一个内联注释:

salary = salary * 1.02 # 增加工资2%

文档字符串是放在代码块(例如函数)的第一行的字符串字面量。

与常规注释不同，文档字符串可以在运行时使用obj.doc属性访问，其中obj是函数名。

通常，您可以使用文档字符串自动生成代码文档。

文档字符串称为文档字符串。

从技术上讲，文档字符串不是注释。它们创建引用字符串的匿名变量。而且，它们不会被Python解释器忽略。

Python提供两种文档字符串:单行文档字符串和多行文档字符串。

顾名思义，单行文档字符串适合一行。单行文档字符串以三重引号(""")开头，也以三重引号(""")结尾。此外，在单行文档字符串之前和之后都不会有任何空行。

下面的例子演示了quicksort()函数中的单行文档字符串:

def quicksort():
"""使用快速排序算法对列表进行排序"""
...

与单行文档字符串不同，多行文档字符串可以跨多行。多行文档字符串也以三重引号(""")开始，以三重引号(""")结束。

下面的例子展示了如何使用多行文档字符串:

def increase(salary, percentage, rating):
    """ 
    按评级和百分比增加工资
    级别 1 - 2 不增加
    级别 3 - 4 增加 5%
    级别 4 - 6 增加 10%
    """

Python不支持多行注释。

但是，你可以使用多行文档字符串作为多行注释。Python的创建者Guido van Rossum也推荐这种方法。

让你的注释保持清晰、简洁和解释性是一个很好的做法。最终目标是为你和其他稍后将处理代码的开发人员节省时间和精力。