Python入门教程第11篇 代码注释

Posted 2022-02-01 不剪发的Tony老师

本篇我们将会学习如何为 Python 代码添加注释，包括块注释、行内注释以及文档注释。

Python 注释

代码注释可以帮助我们理解代码的作用，方便交流和维护。通常，我们需要为公式、算法以及复杂业务逻辑添加注释。

Python 解释器在执行程序时会忽略其中的代码注释。

Python 提供了三种代码注释：块注释（block comment）、行内注释（inline comment）以及文档注释（documentation string）。

块注释

块注释用于解释后续代码的作用，通常块注释的缩进和代码块保持一致。

块注释以井号（#）开始，后面是一个空格和注释的文本。例如：

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

行内注释

行内注释和代码位于同一行，直接写在代码的后面。

行内注释和块注释类似，也是以井号（#）开始，后面是一个空格和注释的文本。例如：

salary = salary * 1.02   # 薪水增加 2%

文档注释

文档注释是代码块（例如函数）中最开始的一段字符串，文档注释和普通注释不同支持在于它可以在运行时通过 obj.__doc__ 属性获取，其中 obj 是函数的名称。

文档注释通常用于生产代码文档，也被称为 docstring。

从技术上来讲，docstring 不是注释。Python 会创建一个匿名的变量，指向文档注释。另外，它们不会被 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 的发明者 Guido van Rossum 也推荐这种用法。

代码注释的最佳实践是保持注释言简意赅，最终的目的是方便自己和其他人阅读和理解代码。

总结

• 为代码添加必要的注释。
• 块注释和行内注释使用井号开始（#），直到当前行结束。
• 为函数、模块以及类添加文档注释。