[Python基础语法]注释

这篇教程将向您展示关于Python注释的知识。

注释就是其字面意思，即对程序进行补充说明，但是不影响程序执行。注释使程序更具可读性和可维护性。

Python注释支持三种注释方式：

1. 单行注释
2. 多行注释
3. 文档注释

单行注释

---

单行注释以井号（＃）开头，并自动以EOL（行尾）结束。

>>> # 输出Hello, World!
... print("Hello, World!")
Hello, World!

注释与其下方的代码处于同一缩进级别

>>> def sum(a, b):
...     # 计算并返回a + b的值
...     return a + b
... 
>>> sum(2, 3)
5

多行注释

---

Python允许注释跨越多行。此类注释称为多行注释或块注释。

要添加多行注释，使用井号（＃）后跟单个空格开始每一行。也可以将注释分成段落。只需在每个段之间添加一个带有井号（＃）的空行。

>>> # 要学习任何语言，您必须遵守以下规则。
... # 1. 了解基本语法，数据类型，控制结构和条件语句。
... # 2. 学习错误处理和文件I/O。
... # 3. 了解高级数据结构。
... # 4. 编写函数并学习面向对象概念。
... 
>>> "Let's start to learn Python."
"Let's start to learn Python."

文档注释

---

文档注释是为每个Python模块，函数，类和方法添加快速注释。它必须是对象（模块，函数，类和方法）定义中的第一个语句。

使用'''来定义文档注释

>>> def pow(a, n):
...     '''
... 计算并返回a的n次方。
...     '''
...     return a ** n
... 
>>> pow(2, 10)
1024
>>> print(pow.__doc__)

计算并返回a的n次方。
    

另外，我们也可以通过pydoc3命令生成注释文档。

$ ls -l /usr/local/bin/pydoc3 
lrwxr-xr-x  1 root  wheel  68 Sep 30 10:14 /usr/local/bin/pydoc3 -> ../../../Library/Frameworks/Python.framework/Versions/3.7/bin/pydoc3
------------
docstring.py文件
-------------
def pow(a, n):
    '''
计算并返回a的n次方
    '''
    return a ** n

-------------
$  pydoc3 ./docstring.py 
Help on module docstring:

NAME
    docstring

FUNCTIONS
    pow(a, n)
        计算并返回a的n次方

FILE
    /Users/xxx/Desktop/Python/docstring.py