关于小悟志网站地图归档友情链接联系Feed

云上小悟 + 

当前位置 : 首页 » InfoTech » 使用Python的docstring 正文

使用Python的docstring

InfoTech
2017年8月25日 / 28次阅读
标签:麦新杰用Python

拍拍贷

文章《使用Python的docstring》的特色图片

程序员一直以来都有一个烦恼,他们只想写代码,不想写文档。他们说:代码就表达了我的思想和灵魂。

小公司相对随意一些,可以先写代码调试,但是最后老板害怕程序员离职造成“青黄不接”,还是会要求补上文档。大公司要求更高,要先写文档,评审通过,然后再开始编码。有的程序员整天都在写文档,苦不堪言。

Python提出了一个方案,叫docstring,来试图解决这个问题。即编写代码,同时也能写出文档,保持代码和文档的一致。

Python提出的这个方案其实并不新鲜,docstring说白了就是一堆代码中的注释。任何编程语言都有注释的好不好!!不过,Python的docstring可以通过help函数直接输出一份有格式的文档,这个就厉害了。代码写完,注释写完,一个help调用,就有文档看了。

 

docstring可以写在三个地方:模块或包,对象,函数。

(以下示例使用著名的requests包)

 

对于模块,docstring就是在模块文件的最前面,如下示例:

docstring使用三个双引号(”),或者三个单引号(‘)都是可以的。

 

对于包,docstring就是在package的__init__.py这个文件的任何语句的前面(docstring的前面还可以有#注释),如下示例:

 

对于函数,docstring就是在函数定义的最前面,如下示例:

注意上例的三个双引号前有个r,r是raw的意思,表示这个字符串里面的\就是它自己,不是用来转意的。

 

对于对象定义,docstring就是在class定义的最前面,如下示例:

 

还有一种单行docstring的写法,如下:

 

Python builtin的help函数主要是在交互模式下使用,在交互模式下,使用help,就能够看到文档中的这些被称为docstring的注释,被一种良好的格式显示出来。

在调整代码的时候,维护注释,维护docstring,进而保持代码和文档(help函数的输出)一致,麦新杰认为是一种简化的思想。docstring不是强制的,如果不写,help函数的输出就是空空的。

下面是help(requests)的输出:

看description部分,这就是写requests包的__init__.py文档中的docstring。

而且还可以看出,help函数不仅输出docstring,还有一些其它的格式化的输出信息,非常handy呀。

 

专业的Python docstring文档,请参考PEP257

您可能要先看一下:什么是PEP文档?

 

Python这种语言简单易学,有个原因就是它将一些复杂的事情简化了,比如非强制的docstring,比如强制缩进。

本文链接:http://www.maixj.net/ict/python-docstring-16247
云上小悟 麦新杰(QQ:1093023102)

-- (*^-^*) --

相关文章

评论是美德

无力满足评论实名制,评论对非实名注册用户关闭,有事QQ:1093023102.


前一篇:
后一篇:

栏目精选


©Copyright 麦新杰 Since 2014 云上小悟独立博客版权所有 备案号苏ICP备14045477号-1

网站二维码
拍拍贷
go to top