008.Python学习笔记：Day8-文档注释

Python学习笔记：Day8-文档注释

现在我们开始要写代码了。下面一段代码实例。

__author__ = 'Fengwangbeichui'
# -*- coding: UTF-8 -*-

我们会注意到文档中会添加一些文档注释，比如作者、编码、功能说明、函数说明等。这就需要我们了解文档注释。

文档注释

对一个库、脚本、函数，如果半年或多年以后再次使用，我们要重新查看代码才能掌握如何使用它。为了解决这种问题，引入了的文档注释。

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

对于每个Python库、脚本、函数等，注释相当于功能说明。注释就如同家用电器使用说明书一样，我们不要知道它的内部工作原理，只要知道如何使用即可。

既然我们程序员，写的脚本也是写给程序员和自己看的。那么为了方便用户使用，我们在写文档注释时应遵守用户认可的注释规范，好方便用户使用。

注释作用

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

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

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

Python3 注释

Python3中的注释有单行注释和多行注释。Python中单行注释以 # 开头。多行注释用三个单引号'''或者三个双引号"""将注释括起来。例如：

#使用 print() 内置函数输出字符串
print("简书：风往北吹_665f")

"""
使用三个连续的单引号或双引号分别作为注释的开头和结尾可以一次性注释多行内容或单行内容，
"""

为函数设置注释文档

定义一个比较数字大小的函数

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__)

运行结果：

--- 用 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