Python注释规范

阅读文本需要5分钟

代码注释是一件很重要的事情，如果你写的一段函数给别人调用那么往往都需要配上一些基本的注释。写好代码可以让别人容易阅读你的代码。试想一 下：如果你在github上面找到一段你想要的代码，这段代码有200行，可能这些代码我们要进行改造，那么这时候如果代码中都没有恰当的注释，我们可能要用比较久的时间去通读一下他的代码。

相反，如果这些代码有一些恰当的注释，我们可能会更加好理解一点。学会注释是编码过程中不可或缺的一部分。那么什么样的注释才是规范的注释，才能让其他看你代码的人能快速的了解你得代码结构呢。今天就说一说 有关于Python的一些注释规范。

在说规范之前有必要先看以下Python的注释有哪些?

• 单行注释

• 多行注释

• 特殊注释

按照每一个注释进行简单的介绍(截选request库的一段文件)：

第1行、第2行：为上述所说的特殊注释，这两个注释也几乎是在你所编写的每一个py文件中应该存在的，正常情况下第一第二行通用格式。

特殊注释

关于#!/usr/bin/env python

• 必须是文件的第一行

• 必须以#!开头

关于#!/usr/bin/env python

• 告诉LINUX/UNIX去找到python的翻译器。

关于： # -*- coding: utf-8 -*-

• 基本上在文件的第二行，在#!/usr/bin/env python的下一行

• python interpret如何解释字符串的编码

• 当你的文件中出现中文的时候，你必须使用它

多行注释

以三个引号开始，三个引号结尾。这三个引号可以使单引号也可以是双引号。一般类文档，函数文档，字符串之类的用双引号，变量用单引号。

第二十一行：我们所说的单行注释，单行注释以#开头标识。

你也可以连续多次使用#单行注释来代替多行注释，但是我们并不推荐那么做。

如何使用注释

知道了上述的注释之后，我们需要知道的是在哪些场合使用哪些注释。

第一点：

为了避免麻烦，在文件的开头加上这两句。

1#!/usr/bin/env python   
2# -*- coding: utf-8 -*

第二点：

每一个Python文件的开头，紧接着第一点所说的两行代码之后，我们往往要写上关于这个模块即这个Python文件实现的功能一些注意点，可能会发生的错误，总之你得注释要让使用它的人很明白你得代码段，比如：

1"""
2requests.cookies  
3~~~~~~~~~~~~~~~~   
4Compatibility code to be able to use `cookielib.CookieJar` with requests. 
5requests.utils imports from here, so be careful with imports.  
6"""

或者

1"""
2This is the Scrapy engine which controls the Scheduler, Downloader and Spiders.
3For more information see docs/topics/architecture.rst 
4"""

可能，你不看代码，都已经知道接下来的是什么了，那么你能找到上面这个注释是出自哪个文件吗?

第三点：

每一个类下面加上关于这个类的说明以及用法，这样使用它的人可能都不要知道他的内部构造，就可以使用他了，我们看看这个。

1. 这个类是干嘛的?

2. 经常在什么情况下使用?

3. 如何使用?

都交待说明的很详细，你不看代码估计已经会使用了。

1class HTTPAdapter(BaseAdapter): 
2"""The built-in HTTP Adapter for urllib3.   
3Provides a general-case interface for Requests sessions to contact HTTP and 
4HTTPS urls by implementing the Transport Adapter interface. 
5This class will   usually be created by …… 
6"""

第四点：

每一个函数下面务必加上多行注释，很有可能你的函数注释只有一行，或者两行，你可以使用单行注释，也可以使用多行注释，这里与类函数说明相当，注释中往往包含使用说明，注意点。

1def __setstate__(self, state):    
2# Can't handle by adding 'proxy_manager' to self.__attrs__ because    
3# self.poolmanager uses a lambda function, which isn't pickleable.

或者

1def has_capacity(self):  
2"""Does the engine have capacity to handle more spiders"""  
3return not bool(self.slot)

第五点：

在必要的地方加上单行注释。这些地方不外乎

1. 你不怎么理解的代码

2. 别人可能不理解的代码

3. 提醒自己或者别人注意的代码、重要代码

1self.inprogress = set() # requests in progress assert not self.running, "Engine already running"

更多的编码习惯。可以去读一读request的代码。

TODO注释

TODO表示需要做而未做的一些待完成的事项，有助于事后的检索，以及对整体项目做进一步的修改迭代。

1# TODO([e-mail]): Use a "*" here for string repetition.
2# TODO(Zeke) Change this to use relations.

最好在注释中包含一个截止日期（“2009年11月解决”）或等待一个特定事件的发生（“等到所有的客户都可以处理XML请求就移除这些代码”）。

一些基本要求和规范：

• TODO注释应该在所有开头处包含”TODO”字符串,

• 紧跟着是用括号括起来的你的名字, email地址或其它标识符.

• 然后是一个可选的冒号. 接着必须有一行注释, 解释要做什么. 主要目的是为了有一个统一的TODO格式,

• 这样添加注释的人就可以搜索到(并可以按需提供更多细节).

在 PyCharm 中，使用 Alt + 6 快捷键，可快速调出项目中的全部 TODO 注释；

  推荐阅读：

↓ ↓ ↓ 戳这里查看官方文档哦