在說規范之前我們有必要先看以下Python的注釋有哪些?
單行注釋
多行注釋
特殊注釋
按照每一個注釋進行簡單的介紹(我們截選request庫的一段文件)：
第一行第二行：為上述所說的特殊注釋，這兩個注釋也幾乎是在你所編寫的每一個py文件中應該存在的，正常情況下第一第二行通用格式。
關於 #!/usr/bin/env python
1、必須是文件的第一行
2、必須以#!開頭
3、#!/usr/bin/env python告訴LINUX/UNIX去找到python的翻譯器。
關於： # -*- coding: utf-8 -*-
1、基本上在文件的第二行，在#!/usr/bin/env python的下一行
2、python interpret如何解釋字符串的編碼
3、當你的文件中出現中文的時候，你必須使用它
第四到第十三行：為上述所說的所行注釋。多行注釋，以三個引號開始，三個引號結尾。這三個引號可以使單引號也可以是雙引號。
1、一般類文檔，函數文檔，字符串之類的用雙引號，變量用單引號。
第二十一行：我們所說的單行注釋，單行注釋以#開頭標識。
你也可以連續多次使用#單行注釋來代替多行注釋，但是我們並不推薦那麼做。
知道了上述的注釋之後，我們需要知道的是在哪些場合使用哪些注釋。
第一點：為了避免麻煩，在文件的開頭加上這兩句。
#!/usr/bin/env python # -*- coding: utf-8 -*
第二點：每一個Python文件的開頭，緊接著第一點所說的兩行代碼之後，我們往往要寫上關於這個模塊即這個Python文件實現的功能一些注意點，可能會發生的錯誤，總之你得注釋要讓使用它的人很明白你得代碼段，比如：
""" requests.cookies ~~~~~~~~~~~~~~~~ Compatibility code to be able to use `cookielib.CookieJar` with requests. requests.utils imports from here, so be careful with imports. """
或者
""" This is the Scrapy engine which controls the Scheduler, Downloader and Spiders. For more information see docs/topics/architecture.rst """
可能，你不看代碼，都已經知道接下來的是什麼了，那麼你能找到上面這個注釋是出自哪個文件嗎?
第三點：每一個類下面加上關於這個類的說明以及用法，這樣使用它的人可能都不要知道他的內部構造，就可以使用他了，我們看看這個。
第一：這個類是干嘛的?
第二：經常在什麼情況下使用?
第三：如何使用?
都交待說明的很詳細，你不看代碼估計已經會使用了。
class HTTPAdapter(BaseAdapter):
"""The built-in HTTP Adapter for urllib3.
Provides a general-case interface for Requests sessions to contact HTTP and
HTTPS urls by implementing the Transport Adapter interface. This class will
usually be created by the :class:`Session ` class under the
covers.
:param pool_connections: The number of urllib3 connection pools to cache.
:param pool_maxsize: The maximum number of connections to save in the pool.
:param max_retries: The maximum number of retries each connection
should attempt. Note, this applies only to failed DNS lookups, socket
connections and connection timeouts, never to requests where data has
made it to the server. By default, Requests does not retry failed
connections. If you need granular control over the conditions under
which we retry a request, import urllib3's ``Retry`` class and pass
that instead.
:param pool_block: Whether the connection pool should block for connections.
Usage::
>>> import requests
>>> s = requests.Session()
>>> a = requests.adapters.HTTPAdapter(max_retries=3)
>>> s.mount('http://', a)
"""
第四點：每一個函數下面務必加上多行注釋，很有可能你的函數注釋只有一行，或者兩行，你可以使用單行注釋，也可以使用多行注釋，這裡與類函數說明相當，注釋中往往包含使用說明，注意點。
def __setstate__(self, state): # Can't handle by adding 'proxy_manager' to self.__attrs__ because # self.poolmanager uses a lambda function, which isn't pickleable.
或者
def has_capacity(self): """Does the engine have capacity to handle more spiders""" return not bool(self.slot)
第五點：在必要的地方加上單行注釋。這些地方不外乎
1、你不怎麼理解的代碼
2、別人可能不理解的代碼
3、提醒自己或者別人注意的代碼、重要代碼
self.inprogress = set() # requests in progress assert not self.running, "Engine already running"
以上，更多的編碼習慣。你可以去讀一讀，request的代碼。
