**将注释放在Python语法前面足以提现它的重要性。**

## 注释的作用

一个好的程序中注释是不可缺失的一环。在程序中对某些代码进行标注说明，可以增强程序的可读性。在团队协同开发中，良好的注释可以提高开发效率。

## 什么时候需要使用注释？

- **注释不是越多越好**，对于一目了然的代码，不需要添加注释

- 对于 **复杂的操作**，应该在操作开始前写上思路的注释

- 对于 **不是一目了然的代码**，应在其行尾添加注释(为了提高可读性，注释应该至少离开代码 2 个空格)

- 绝不要描述代码，假设阅读代码的人比你更懂 Python，他只是不知道你的代码要做什么


## 注释类型

### 单行注释

以 `#` 开头，`#` 右边的所有东西都被当做说明文字，而不是真正要执行的程序，只起到辅助说明作用

*为了保证代码的可读性，*`#` *后面建议先添加一个空格，然后再编写相应的说明文字*。需要注意的是，**为了保证代码的可读性**，**注释和代码之间** 至少要有 **两个空格**



### 多行注释

如果要写的注释信息很多，一行无法写完，就可以使用多行注释。在Python程序中使用多行注释，可以用**一对连续的三个引号**(单引号和双引号都可以)。

### 文档

Python有一种独一无二的的注释方式: 使用文档注释。文档注释是包、模块、 类或函数里的第一个语句。这些注释可以通过对象的\_\_doc\_\_成员被自动提取, 并且被pydoc所用.对文档注释的惯例是使用三重双引号"""( [PEP-257](http://www.python.org/dev/peps/pep-0257/) )。一个文档注释应该这样组织: 首先是一行以句号，问号或惊叹号结尾的概述(或者该文档注释单纯只有一行)。接着是一个空行，接着是文档注释剩下的部分，它应该与文档注释的第一行的第一个引号对齐。

### 模块

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

### 函数和方法

下文所指的函数,包括函数、方法以及生成器。一个函数必须要有文档字符串, 除非它满足以下条件:

- 外部不可见

- 非常短小

- 简单明了

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

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

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

**Returns(或者 Yields: 用于生成器)**： 描述返回值的类型和语义。如果函数返回None，这一部分可以省略。

**Raises**：列出与接口有关的所有异常。

### 类

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

[Python风格规范-注释](https://zh-google-styleguide.readthedocs.io/en/latest/google-python-styleguide/python_style_rules/#comments)