使用注释

1 规范

1.1 单行注释

使用#号进行注释 如： #单行注释 

1.2 多行注释

文档字符串，是包、模块、类、函数的第一个语句，可以通过对象的doc 属性被自动提取，也可以被pydoc工具提取。 使用三个双引号或单引号来注释多行内容 如：

'''
单引号进行多行注释
'''
"""
双引号进行多行注释
"""

1.3 注释位置

文档字符串型注释，用来对模块、类、函数进行说明，放在模块文件开头，类和函数的第一个语句，起到说明的作用。

模块：

每个文件应该包含一个许可样板. 根据项目使用的许可(例如, Apache 2.0, BSD, LGPL, GPL), 选择合适的样板

类：

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

功能详细说明 Attributes： one: 第一个属性

函数：

下文所指的函数,包括函数, 方法, 以及生成器.

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

1.外部不可见 2.非常短小

3.简单明了

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

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

Args：需要的参数 列出每个参数的名字, 并在名字后使用一个冒号和一个空格, 分隔对该参数的描述.如果描述太长超过了单行80字符,使用2或者4个空格的悬挂缩进(与文件其他部分保持一致). 描述应该包括所需的类型和含义. 如果一个函数接受foo(可变长度参数列表)或者bar (任意关键字参数), 应该详细列出foo和**bar

Return(Yields)：返回的类型 描述返回值的类型和语义. 如果函数返回None, 这一部分可以省略.

Raises：抛出的异常 列出与接口有关的所有异常.

块注释和行注释，主要用来说明代码中用到的技巧部分，防止下次看时，遗忘。

对于复杂的操作, 应该在其操作开始前写上若干行注释. 对于不是一目了然的代码, 应在其行尾添加注释.

2 工具

python3 自带了一个注释文档生成工具，pydoc，可以基于注释生成帮助文档

生成命令：

# 启用一个web服务进行查看, 这里启动 8888端口的一个web服务
python -m pydoc -p 8888
# 直接查看一个 文件
python -m pydoc file.py
# 生成html文件
python -m pydoc [file or dir]
# 关键词查找
python -m pydoc -k [关键词]

3 Html说明

class展示

1.只能展示class下的注释，不会展示class下方法的注释 2.class上面有#注释时，展示#号的注释 3.class下有”””多行注释”””时优先展示多行注释，就不展示顶部的#号的注释了

function展示

1.function上面有#注释时，展示#号的注释 2.function下有”””多行注释”””时优先展示多行注释，就不展示顶部的#号的注释了

目录