Python基础——注释

Python基础——注释

1.1、 Python的注释

1.1.1、 Python的注释概述

注释（Comments）是用来向开发者（用户）提示或解释某些代码的思路、作用和功能等，可以添加到代码中的任何位置。Python 解释器（Python Interpreter）在执行程序（代码）时会忽略注释部分，不做任何处理，即注释部分不会被 Python 解释器执行。

在代码中添加适当的注释量很重要，注释通常占源代码的 1/3 左右。

Python 支持两种类型的注释：单行注释和多行注释。

1.1.2、 Python 注释的作用

1.1.2.1、 调试代码

在调试（Debug）程序的过程中，单行注释可以用来临时快速注释某些代码，达到缩小错误范围、提高调试程序效率的目的。

具体操作如下：
​ 在不确定具体是哪一行代码出错的情况下，我们可以先把觉得可能有问题的代码注释起来，然后再运行程序观察结果。如果程序可以正常执行，则可以说明错误就是由这段代码引起的；反之，如果依然出现相同的错误，则可以说明错误不是由这段代码引起的。

1.1.2.2、 提高程序的可读性

注释的最大作用是提高程序的可读性，没有注释的程序是很难让人看懂的，说是天书也不为过。
更甚至，自己写的代码，过了一段时间以后，自己也会忘记思路或者目的。

1.1.3、 Python 单行注释

1.1.3.1、 Python 单行注释概述

Python 中是使用井号#作为单行注释的符号，其语法格式如下所示：

1
# 添加的注释内容

对以上语法格式的说明：

  • #作为单行注释的符号。
  • 从井号#开始，直到这行结束为止的所有内容都是注释。Python 解释器遇到#时，会忽略它后面的整行内容，即#之后的一行内容都属于注释部分。
1.1.3.2、 单行注释注释单行代码的情况

单行注释注释单行代码时通常会将注释放在代码的右侧，与代码之间用两个空格隔开，如下所示：

1
2
3
print("洋群满满")  # 输出网站的名称名称
print('yangyangmm.cn')  # 输出本网站地址
print('https://blog.csdn.net/weixin_45278644')  # 输出洋群满满的CSDN博客地址
1.1.3.3、 单行注释注释多行代码的情况

单行注释注释多行代码时通常将注释放在代码的上一行，如下所示：

1
2
3
4
5
6
7
8
9
# 使用 print() 内置函数输出字符串
print("网站的名称名称：洋群满满")  
print('本网站地址：yangyangmm.cn')  
print('CSDN博客地址： https://blog.csdn.net/weixin_45278644') 

# 使用 print() 内置函数输出数字
print(520)
print(521)
print(1314)

1.1.4、 单行注释注意事项

1.1.4.1、 单行注释符号作为字符串的一部分存在

当单行注释符号#作为字符串的一部分出现时，就不能再将它当做单行注释标记，而应该当做是字符串的一部分（字符串的字符），如下所示：

1
2
3
print('# 网站的名称名称：洋群满满')
print("# 本网站地址：yangyangmm.cn")
print("# CSDN博客地址： https://blog.csdn.net/weixin_45278644")

运行结果：

1
2
3
# 网站的名称名称：洋群满满
# 本网站地址：yangyangmm.cn
# CSDN博客地址： https://blog.csdn.net/weixin_45278644

对以上代码说明：

  • Python 没有将井号#当做单行注释标记，而是将它当做字符串的一部分。

1.1.5、Python 多行注释

1.1.5.1、 Python 多行注释概述

多行注释指的是一次性注释程序中多行代码，也可以是一行代码。

Python 中支持使用三个连续的单引号'''分别作为注释的开头和结尾，或者三个连续的双引号"""分别作为注释的开头和结尾，一次性注释多行或单行内容。

多行注释通常用来为 Python 函数、类、模块等等添加功能、版本和作者等描述信息。

1.1.5.2、 三个连续的单引号注释

三个连续的单引号注释内容具体格式如下：

1
2
3
4
'''
使用三个连续的单引号分别作为注释的开头和结尾
可以一次性注释多行内容或单行内容
'''
1.1.5.3、 三个连续的双引号注释
1
2
3
4
"""
使用三个连续的双引号分别作为注释的开头和结尾
可以一次性注释多行内容或单行内容
"""
1.1.5.4、 多行注释也可以为函数提供说明文档

在 Python 中可以通过 help()内置函数或者__doc__属性查看某个函数的说明文档，如下代码所示：

1
2
3
4
5
# 查看 print() 内置函数的说明文档
print('--- 用 help()内置函数查看说明文档 ---')
help(print)
print('--- 用 __doc__ 属性查看说明文档 ---')
print(print.__doc__)

运行结果：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
--- 用 help()内置函数查看说明文档 ---
Help on built-in function print in module builtins:

print(...)
    print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)
    
    Prints the values to a stream, or to sys.stdout by default.
    Optional keyword arguments:
    file:  a file-like object (stream); defaults to the current sys.stdout.
    sep:   string inserted between values, default a space.
    end:   string appended after the last value, default a newline.
    flush: whether to forcibly flush the stream.

--- 用 __doc__ 属性查看说明文档 ---
print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)

Prints the values to a stream, or to sys.stdout by default.
Optional keyword arguments:
file:  a file-like object (stream); defaults to the current sys.stdout.
sep:   string inserted between values, default a space.
end:   string appended after the last value, default a newline.
flush: whether to forcibly flush the stream.

其实，函数的说明文档，本质就是一段字符串（跟多行注释符号一致），都需要程序员自己编写，只不过作为说明文档，字符串的放置位置不同而已，函数的说明文档通常位于函数内部、所有代码的最前面。

如何为函数设置说明文档呢？如下所示：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# 定义一个比较数字大小的函数
def num_max(num1, num2):
    """
    比较两个数字的大小
    :param num1:形参1，数字1
    :param num2:形参2，数字2
    :return:大的数字，max_num = num1 if num1 > num2 else num2
    """
    max_num = num1 if num1 > num2 else num2
    return max_num


result = num_max(1, 2)
print(result)
print('--- 用 help() 内置函数查看 num_max() 的说明文档 ---')
help(num_max)
print('--- 用 __doc__ 属性查看 num_max() 的说明文档 ---')
print(num_max.__doc__)

运行结果：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
2
--- 用 help() 内置函数查看 num_max() 的说明文档 ---
Help on function num_max in module __main__:

num_max(num1, num2)
    比较两个数字的大小
    :param num1:形参1，数字1
    :param num2:形参2，数字2
    :return:大的数字，max_num = num1 if num1 > num2 else num2

--- 用 __doc__ 属性查看 num_max() 的说明文档 ---

    比较两个数字的大小
    :param num1:形参1，数字1
    :param num2:形参2，数字2
    :return:大的数字，max_num = num1 if num1 > num2 else num2

1.1.6、 多行注释注意事项

1.1.6.1、 多行注释不支持嵌套

Python 多行注释不支持嵌套，如下所示为错误写法：

1
2
3
4
5
6
'''
外层注释
    '''
    内层注释
    '''
'''
1.1.6.2、多行注释符号'''或"""作为字符串标记

多行注释符号'''或"""也可以作为字符串的开始和结束标记。

Python 中当多行注释符号作为字符串的一部分出现时，就不能再将它们当做多行注释标记，而应该看做是字符串的一部分，如下所示：

1
2
3
4
5
6
7
str_info1 = '''网站的名称名称：洋群满满'''
str_info2 = """本网站地址：yangyangmm.cn"""
str_info3 = "CSDN博客地址： https://blog.csdn.net/weixin_45278644"

print(str_info1)
print(str_info2)
print(str_info3)

运行结果：

1
2
3
网站的名称名称：洋群满满
博客园博客地址 本网站地址：yangyangmm.cn
CSDN博客地址： https://blog.csdn.net/weixin_45278644

对以上代码说明：

  • Python 没有将这里的三个引号当做是多行注释，而是将它们看作字符串的开始和结束标志。
Python

本博客所有文章除特别声明外，均采用 CC BY-SA 4.0 协议 ，转载请注明出处！