注释

翻译自：https://www.pythontutorial.net/python-basics/python-comments/

Python注释简介

有时，您需要记录自己编写的代码。例如，您可能想说明一段代码为何有效。为此，您可以使用注释。

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

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

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

Python 块注释

块注释解释了其后的代码。通常，块注释的缩进级别与代码块相同。

要创建块注释，请以单个井号 ( #) 开头，后跟单个空格和文本字符串。例如：

# increase price by 5%
price = price * 1.05

Python 内联注释

当您将注释放在与语句同一行时，您将获得内联注释。

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

以下示例说明了内联注释：

salary = salary * 1.02   # increase salary by 2%

Python 文档字符串

文档字符串是一个字符串文字，您可以将其作为代码块的第一行放入其中，例如函数。

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

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

文档字符串被称为docstrings。

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

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

1）单行文档字符串

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

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

def quicksort():
""" sort the list using quicksort algorithm """
...

2）多行文档字符串

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

以下示例展示如何使用多行文档字符串：

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 不支持多行注释。

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

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