注释

未匹配的标注

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

注释的作用

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

什么时候需要使用注释?

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

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

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

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

注释类型

单行注释

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

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

多行注释

如果要写的注释信息很多,一行无法写完,就可以使用多行注释。在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 >}}

本文章首发在 LearnKu.com 网站上。

上一篇 下一篇
讨论数量: 0
发起讨论 只看当前版本


暂无话题~