Python注释

摘要：在本节中，你将学习如何为代码添加注释。你还将学习各种类型的 Python 注释，包括块注释、行内注释和文档字符串。

Python注释简介

有时，你希望为所编写的代码添加文档说明。例如，你可能希望记录某段代码为何能正常工作。为此，你可以使用注释。

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

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

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

块注释

块注释用于解释其后的代码。通常，你会将块注释缩进到与代码块相同的级别。

要创建块注释，你可以以单个井号（#）开头，后面跟一个空格和一个文本字符串。例如：

# increase price by 5%

price = price * 1.05

Python 行内注释

当您将注释与代码语句放在同一行时，就形成了行内注释。

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

下面的例子展示了一个行内注释：

salary = 120000

salary = salary * 1.02   # increase salary by 2%

print(salary)

输出：

122400.0

Python 文档字符串（docstrings）

文档字符串是一种字符串字面量，通常放置在代码块（例如函数）的首部。

与普通注释不同，文档字符串可以在运行时通过 obj.__doc__ 属性访问，其中 obj 是函数名。

通常，文档字符串用于自动生成代码文档。

文档字符串也被简称为 docstrings。

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

Python 提供了两种类型的文档字符串：单行文档字符串 和 多行文档字符串。

单行文档字符串

顾名思义，单行文档字符串仅占一行。它以三个引号（"""）开头，并以三个引号（"""）结尾。此外，在单行文档字符串的前后都不会有空行。

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

def quicksort():

""" sort the list using quicksort algorithm """

...

多行文档字符串

与单行文档字符串不同，多行文档字符串可以跨越多行。它同样以三个引号（"""）开头，并以三个引号（"""）结尾。

下面的例子展示了多行文档字符串的用法：

def increase(salary, percentage, rating):

    """ increase salary base on rating and percentage

    rating 1 - 2 no increase

    rating 3 - 4 increase 5%

    rating 4 - 6 increase 10%

    """

Python 多行注释

Python 并不直接支持多行注释语法。

但您可以通过多行文档字符串（docstrings）来实现多行注释的效果。Python 创始人 Guido van Rossum 也曾推荐这种方式。

最佳实践是保持注释清晰、简洁且具有解释性。这样做的最终目的是为您和其他后续开发人员节省时间和精力。

总结

• 在必要时使用注释来记录代码

• 块注释和行内注释均以井号（#）开头

• 文档字符串（docstrings）应用于函数、模块和类的说明