python的类写法_科学网—关于python中,docstring的写法 - 于博的博文

P { margin-bottom: 0.08in; direction: ltr; color: rgb(0, 0, 0); }P.western { font-family: "Times New Roman",serif; font-size: 10pt; }P.cjk { font-family: "Times New Roman",serif; font-size: 10pt; }P.ctl { font-family: "Times New Roman",serif; font-size: 10pt; }A:visited { color: rgb(132, 0, 132); }A.western:visited { }A.cjk:visited { }A.ctl:visited { }A:link { color: rgb(0, 0, 255); }

通常使用的格式"""docstring..."""，如果使用反斜线，用r"""docstring..."""格式，如果使用统一字符编码标准，使用u“”"docstring"""

对于docstrings本身，有两种格式，一种是单行，一种是多行

单行用于简单，明显的情况。要用祈使句来陈述，不要使用函数参数来表达。函数的返回值不是由内省决定的，应该提及。“”“Do sth and return sth."""

多行的docstring包含一行类似于单行docstring的话，再空一行，最后是详细描述。

为一个函数添加docstring,要总结它的作用，参数，返回值，引起的异常，副作用，运行的限制。可选的参数应该说明。关键字参数是否是接口的一部分也要说明。

为一个类添加docstring,要在所有的docstring前面和后面都加一个空行，类中所有的方法之间都由空行分开。共有函数以及实例变量都要列出。如果这个类要有子类，而且对子类有另外的接口，这个接口也要列出来。类的结构也要在docstring说明。每个方法都应该由自己的docstring进行说明。如果一个类是另一个类的子类，它的方法大部分是继承而来，它的docstring应该提及这个，而且总结差异。'override’来描述子类的方法替代了父类方法，用'extend'表达子类的方法扩大了父类方法的功能。

为一个项目添加docstring,要在函数被错误调用或者遗失参数的时候输出。应该陈述项目的函数，命令行语法，环境变量以及文件。

为一个module添加的docstring应该为每个包含的类，异常情况以及函数添加一行的docstring总结。

为一个安装包添加的docstring也应列出modules和子安装包

利用docstring列参数时，最好每个参数一行

例如：def complex(real=0.0, imag=0.0):

"""Form a complex number.

Keyword arguments:

real -- the real part (default 0.0)

imag -- the imaginary part (default 0.0)

"""

if imag == 0.0 and real == 0.0: return complex_zero

...

转载本文请联系原作者获取授权，同时请注明本文来自于博科学网博客。

链接地址：http://blog.sciencenet.cn/blog-571755-706647.html

上一篇：python raw_input与input

下一篇：python中dictionary的用法小结