注冊用戶即可下載全站資源 關注Java幫幫微信公眾號
 

Python里的一些注釋規范

10
發表時間:2019-06-26 10:42

寫代碼注釋是一件很重要的事情,如果你寫的一段函數給別人調用那么往往都需要配上一些基本的注釋。寫好代碼可以讓別人容易閱讀你的代碼。試想一 下:如果你在github上面找到一段你想要的代碼,這段代碼有200行,可能這些代碼我們要進行改造,那么這時候如果代碼中都沒有恰當的注釋,我們可能 要用比較久的時間去通讀一下他的代碼。

相反,如果這些代碼有一些恰當的注釋,我們可能會更加好理解一點。學會注釋是編碼過程中不可或缺的一部分。那么什么樣的注釋才是規范的注釋,才能讓其他看你代碼的人能快速的了解你得代碼結構呢。我們今天就說一說 有關于Python的一些注釋規范。

在說規范之前我們有必要先看以下Python的注釋有哪些?

單行注釋

多行注釋

特殊注釋

日本韩国三级aⅴ在线观看按照每一個注釋進行簡單的介紹(我們截選request庫的一段文件):


Python里的一些注釋規范0
第一行第二行:為上述所說的特殊注釋,這兩個注釋也幾乎是在你所編寫的每一個py文件中應該存在的,正常情況下第一第二行通用格式。


關于 #!/usr/bin/env python

1、必須是文件的第一行

2、必須以#!開頭

3、#!/usr/bin/env python告訴LINUX/UNIX去找到python的翻譯器。

關于: # -*- coding: utf-8 -*-

日本韩国三级aⅴ在线观看1、基本上在文件的第二行,在#!/usr/bin/env python的下一行

2、python interpret如何解釋字符串的編碼

3、當你的文件中出現中文的時候,你必須使用它

日本韩国三级aⅴ在线观看第四到第十三行:為上述所說的所行注釋。多行注釋,以三個引號開始,三個引號結尾。這三個引號可以使單引號也可以是雙引號。

日本韩国三级aⅴ在线观看1、一般類文檔,函數文檔,字符串之類的用雙引號,變量用單引號。

日本韩国三级aⅴ在线观看第二十一行:我們所說的單行注釋,單行注釋以#開頭標識。

日本韩国三级aⅴ在线观看你也可以連續多次使用#單行注釋來代替多行注釋,但是我們并不推薦那么做。

知道了上述的注釋之后,我們需要知道的是在哪些場合使用哪些注釋。

第一點:為了避免麻煩,在文件的開頭加上這兩句。

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

日本韩国三级aⅴ在线观看第二點:每一個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"""

可能,你不看代碼,都已經知道接下來的是什么了,那么你能找到上面這個注釋是出自哪個文件嗎?

第三點:每一個類下面加上關于這個類的說明以及用法,這樣使用它的人可能都不要知道他的內部構造,就可以使用他了,我們看看這個。

第一:這個類是干嘛的?

日本韩国三级aⅴ在线观看第二:經常在什么情況下使用?

第三:如何使用?

日本韩国三级aⅴ在线观看都交待說明的很詳細,你不看代碼估計已經會使用了。

classHTTPAdapter(BaseAdapter):"""The built-in HTTP Adapter for urllib3.Provides a general-case interface for Requests sessions to contact HTTP andHTTPS urls by implementing the Transport Adapter interface. This class willusually be created by the :class:`Session ` class under thecovers.: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 connectionshould attempt. Note, this applies only to failed DNS lookups, socketconnections and connection timeouts, never to requests where data hasmade it to the server. By default, Requests does not retry failedconnections. If you need granular control over the conditions underwhich we retry a request, import urllib3's ``Retry`` class and passthat 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.

或者

defhas_capacity(self):"""Does the engine have capacity to handle more spiders"""returnnot bool(self.slot)

第五點:在必要的地方加上單行注釋。這些地方不外乎

1、你不怎么理解的代碼

日本韩国三级aⅴ在线观看2、別人可能不理解的代碼

3、提醒自己或者別人注意的代碼、重要代碼

self.inprogress = set()# requests in progressassertnot self.running,"Engine already running"

以上,更多的編碼習慣。你可以去讀一讀,request的代碼。

本文最初發表在,文章內容屬作者個人觀點,不代表本站立場。


支付寶贊助-Java幫幫社區
微信贊助-Java幫幫社區
Java幫幫公眾號生態

Java幫幫公眾號生態

總有一款適合你

Java幫幫-微信公眾號

Java幫幫-微信公眾號

將分享做到極致

Python幫幫-公眾號

Python幫幫-公眾號

人工智能,爬蟲,學習教程

大數據驛站-微信公眾號

大數據驛站-微信公眾號

一起在數據中成長

九點編程-公眾號

九點編程-公眾號

深夜九點學編程

程序員生活志-公眾號

程序員生活志-公眾號

互聯網,職場,程序員那些事兒

Java幫幫學習群生態

Java幫幫學習群生態

總有一款能幫到你

Java學習群

Java學習群

與大牛一起交流

大數據學習群

大數據學習群

在數據中成長

九點編程學習群

九點編程學習群

深夜九點學編程

python學習群

python學習群

人工智能,爬蟲

測試學習群

測試學習群

感受測試的魅力

Java幫幫生態承諾

Java幫幫生態承諾

一直堅守,不負重望

初心
勤儉
誠信
正義
分享
合作品牌 非盈利生態-優質內容分享傳播者
關于我們
友鏈申請
友鏈交換:加幫主QQ2524138991 留言即可 24小時內答復  
全站內容非商業用途,內容來源于網友,并遵循 許可,如有異議請聯系客服。
會員登錄
獲取驗證碼
登錄
登錄
我的資料
留言
回到頂部