Python学习之路-注释

Python学习之路-注释

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

注释的作用

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

什么时候需要使用注释？

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

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

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

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

{{< admonition tip “提示” true >}}

在一些正规的开发团队，通常会有 代码审核 的惯例一个团队中彼此阅读对方的代码

{{< /admonition >}}

注释类型

单行注释

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

{{< admonition tip “提示” true >}}

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

{{< /admonition >}}

多行注释

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

文档

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

模块

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

函数和方法

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

• 外部不可见

• 非常短小

• 简单明了

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

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

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

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

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

类

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

{{< admonition quote “参考” true >}}

Python风格规范-注释

{{< /admonition >}}