[

1. docstring工具

python是一门高度自省的编程语言,每个对象都有一个__doc__字段用于保存一段自我描述的文本.这个文本可以

被help()内置函数截获;
被标准库pydoc读出生成注释文档;
如果其中包含doctest语法的话也可以被doctest解析用于做测试

在每个模块/类/函数的定义过程中,定义体内的第一行最开头开始如果使用3个引号("""或者''')的形式来构建一个字符串段,那么它就会被赋值给这个对象的__doc__字段,也就是这段字符串就是这个对象的docstring.

1.1. docstrings注释风格

我们的docstrings注释要简洁明了,并且最好符合大多数人的阅读习惯,这样才便于维护,这边推荐谷歌风格的注释规范.

如果使用vscode的话,有一个插件autoDocstring可以非常简单的创建符合各种风格的docstring模板,只需要在config中设置下"autoDocstring.docstringFormat": "google",即可.

1.1.1. 模块docstrings

Python中有模块概念,可以简单的理解为每个文件都是一个模块,而每个文件夹也都是模块.只是文件夹模块的导入文件为其中的__init__.py文件. 通常模块也是要有docstring注释,用于在多人协作时记录一些元信息. 这些元信息包括:

模块简单说明
Version 模块的版本
Author 模块的作者
Email 模块作者的邮箱
Copyright 模块的版权,包括日期和作者
License 模块的许可证样板
History 模块的跟新历史

我们来看一个例子:

"""定义一些标准错误和一些方法.  + File: error.py + Version: 0.5 + Author: hsz + Email: [email protected] + Copyright: 2018-02-08 hsz + License: MIT + History      + 2018-01-23 created by hsz     + 2018-01-23 version-0.5 by hsz """

每个文件应该包含一个许可证样板. 根据项目使用的许可, 选择合适的样板.

1.1.2. 函数docstrings

一个函数必须要有文档字符串, 除非它满足以下条件:

外部不可见
非常短小
命名简单明了

文档字符串应该包含函数做什么, 以及输入和输出的详细描述. 通常, 不应该描述”怎么做”, 除非是一些复杂的算法. 文档字符串应该提供足够的信息, 当别人编写代码调用该函数时, 他不需要看一行代码, 只要看文档字符串就可以了. 对于复杂的代码, 在代码旁边加注释会比使用文档字符串更有意义.

关于函数的几个方面应该在特定的小节中进行描述记录，这几个方面如下文所述. 每节应该以一个标题行开始. 标题行以冒号结尾. 除标题行外, 节的其他内容应被缩进2个空格.

Args: 列出每个参数的名字, 并在名字后使用一个冒号和一个空格, 分隔对该参数的描述.如果描述太长超过了单行80字符,使用2或者4个空格的悬挂缩进(与文件其他部分保持一致). 描述应该包括所需的类型和含义. 如果一个函数接受*foo(可变长度参数列表)或者**bar (任意关键字参数), 应该详细列出*foo和**bar.
Returns: (或者 Yields: 用于生成器) 描述返回值的类型和语义. 如果函数返回None, 这一部分可以省略.
Raises: 列出与接口有关的所有异常.

我们看一个例子:

def flatten(items):     """压扁序列,将多层结构的序列压为一列.       Args:         items (Iterable): 复杂的多层序列     Returns:         Iterable: 压扁后的单层序列     """     for item in items:         is_iterable = isinstance(item, Iterable)         is_string_or_bytes = isinstance(item, (str, bytes, bytearray))         if is_iterable and not is_string_or_bytes:             for i in flatten(item):                 yield i         else:             yield item

1.1.3. 类docstrings

类应该在其定义下有一个用于描述该类的文档字符串. 如果你的类有公共属性(Attributes), 那么文档中应该有一个属性(Attributes)段. 并且应该遵守和函数参数相同的格式.

Attributes: 成员属性

我们看一个例子:

class SampleClass(object):     """一个简单的类例子      Attributes:         likes_spam: 布尔型参数         eggs: int型参数     """      def __init__(self, likes_spam=False):         """Inits SampleClass with blah."""         self.likes_spam = likes_spam         self.eggs = 0      def public_method(self):         """Performs operation blah."""