【每天几分钟，从零入门python编程的世界！】

●为什么要写说明文档？

我们大多数时候都是要跟别人合作，才能完成一个项目，尤其是大型的复杂的项目，通常都是由多人共同合作才能搞定。无论是从团队合作的角度，还是从个人的角度来说，我们都需要写注释或者文档。

从团队协作的角度来说，你写的代码只是整个系统的一部分，别人要在你的代码的基础上进行开发。比如一个项目比较紧急，大家需要接力写代码，你写了一会，累了休息下，另一个人接着你的代码继续写，下一个人再接着他的写，因此你的代码不仅是给自己看的，还是要给其他团队成员看的，再比如你写了一个很厉害的函数，别人可能不知道怎么用，为了方便别人阅读和使用，你就应该写文档或注释给后面人看。

从个人的角度来说，可能你现在写了一个非常复杂的运算在程序里面，你现在是懂的，可能过了一天、一年或者几年后，你想把这个程序维护一下、改进优化一下，那时候你就不一定能看的懂你写的是什么东西了。

Python特点是比较优雅，写文档比较简化，在代码中就可以写文档，就像写注释一样(代码即文档)，而且这些代码文档可以被调用出来，这是非常酷炫而又方便的事情。

实例：

金融领域大家都知道一个词P/E ratio，即市价盈利比率，简称市盈率(Price earnings ratio)，也叫“股价收益比率”。市盈率是某种股票每股市价与每股盈利的比率。

假设我们用一个函数来计算市盈率。

#声明函数

def PE(Price,Earning):

PE=Price/Earning

return print(PE)

#调用函数

PE(20,6)

运行结果为3.333333，即市盈率为3.333333。

假设你现在从事金融行业，你现在知道你定义的这个PE()函数是计算市盈率的，但是也许你2年后转行了，你回过头看，你可能就忘了，你当初写的这个PE()是干什么的，是不是physical education(体育课)？因此在定义这个函数的时候写上文档说明一下是有必要的。

●如何写说明文档？

现在我们以这个PE函数代码为例，来写文档，这个文档是用来解释你写的PE是什么东西。在Python中，写文档就跟写多行注释一样，以3个引号开头和结尾，说明部分写在它们之间。如下：

def PE(Price,Earning):

"""

calculate PE ratio

INPUT:

Price: int or float. The price of the stock you choose.

Earning: int or float. The earning of the stock you choose.

OUTPUT:

PE: Price/Earning. The PE ratio of the stock you choose.

"""

PE=Price/Earning

return print(PE)

未来的你一旦不知道你之前写的这个PE是什么的时候，你就可以通过shell把这个说明文档调出来，非常方便而又清晰明了。

●调用说明文档

调用说明文档只需要写PE.__doc__,就可以调用并把文档代码显示出来。

我是时问新，欢迎关注我。跟我一起从零开始学习Python，每天花一点时间，开启python编程新世界的大门，领略新的风光，让人生多一种可能！