Python將納入高中教材，大學VB將被Python取代，現(xiàn)在你還對Python一無所知嗎？去年就被國外一機構預測，2017年python將是必學語言趨勢，現(xiàn)在看來不假了。
Python 是 Google主要的腳本語言。這本風格指南主要包含的是針對python的編程準則。
為幫助讀者能夠?qū)⒋a準確格式化，我們提供了針對 Vim的配置文件 。對于Emacs用戶，保持默認設置即可。
對你的代碼運行pylint
定義:pylint是一個在Python源代碼中查找bug的工具. 對于C和C++這樣的不那么動態(tài)的(譯者注: 原文是less dynamic)語言, 這些bug通常由編譯器來捕獲. 由于Python的動態(tài)特性, 有些警告可能不對. 不過偽告警應該很少.優(yōu)點:可以捕獲容易忽視的錯誤, 例如輸入錯誤, 使用未賦值的變量等.缺點:pylint不完美. 要利用其優(yōu)勢, 我們有時侯需要: a) 圍繞著它來寫代碼 b) 抑制其告警 c) 改進它, 或者d) 忽略它.結(jié)論:確保對你的代碼運行pylint.抑制不準確的警告,以便能夠?qū)⑵渌姹┞冻鰜怼Ｄ憧梢酝ㄟ^設置一個行注釋來抑制告警. 例如:
pylint警告是以一個數(shù)字編號(如 C0112 )和一個符號名(如 empty-docstring )來標識的. 在編寫新代碼或更新已有代碼時對告警進行醫(yī)治, 推薦使用符號名來標識.
如果警告的符號名不夠見名知意，那么請對其增加一個詳細解釋。
采用這種抑制方式的好處是我們可以輕松查找抑制并回顧它們.
你可以使用命令 pylint --list-msgs 來獲取pylint告警列表. 你可以使用命令 pylint --help-msg=C6409 , 以獲取關于特定消息的更多信息.
相比較于之前使用的 pylint: disable-msg , 本文推薦使用 pylint: disable .
要抑制”參數(shù)未使用”告警, 你可以用”_”作為參數(shù)標識符, 或者在參數(shù)名前加”unused_”. 遇到不能改變參數(shù)名的情況, 你可以通過在函數(shù)開頭”提到”它們來消除告警. 例如
僅對包和模塊使用導入
定義:模塊間共享代碼的重用機制.優(yōu)點:命名空間管理約定十分簡單. 每個標識符的源都用一種一致的方式指示. x.Obj表示Obj對象定義在模塊x中.缺點:模塊名仍可能沖突. 有些模塊名太長, 不太方便.結(jié)論:使用 import x 來導入包和模塊.使用 from x import y , 其中x是包前綴, y是不帶前綴的模塊名.使用 from x import y as z, 如果兩個要導入的模塊都叫做y或者y太長了.例如, 模塊 sound.effects.echo 可以用如下方式導入:
導入時不要使用相對名稱. 即使模塊在同一個包中, 也要使用完整包名. 這能幫助你避免無意間導入一個包兩次.
使用模塊的全路徑名來導入每個模塊
優(yōu)點:避免模塊名沖突. 查找包更容易.缺點:部署代碼變難, 因為你必須復制包層次.結(jié)論:所有的新代碼都應該用完整包名來導入每個模塊.應該像下面這樣導入:
允許使用異常, 但必須小心
定義:異常是一種跳出代碼塊的正?？刂屏鱽硖幚礤e誤或者其它異常條件的方式.優(yōu)點:正常操作代碼的控制流不會和錯誤處理代碼混在一起. 當某種條件發(fā)生時, 它也允許控制流跳過多個框架. 例如, 一步跳出N個嵌套的函數(shù), 而不必繼續(xù)執(zhí)行錯誤的代碼.缺點:可能會導致讓人困惑的控制流. 調(diào)用庫時容易錯過錯誤情況.結(jié)論:異常必須遵守特定條件:
像這樣觸發(fā)異常: raise MyException('Error message') 或者 raise MyException . 不要使用兩個參數(shù)的形式( raise MyException, 'Error message' )或者過時的字符串異常( raise 'Error message' ).
模塊或包應該定義自己的特定域的異常基類, 這個基類應該從內(nèi)建的Exception類繼承. 模塊的異?；悜摻凶觥盓rror”.
永遠不要使用 except: 語句來捕獲所有異常, 也不要捕獲 Exception 或者 StandardError , 除非你打算重新觸發(fā)該異常, 或者你已經(jīng)在當前線程的最外層(記得還是要打印一條錯誤消息). 在異常這方面, Python非常寬容, except: 真的會捕獲包括Python語法錯誤在內(nèi)的任何錯誤. 使用 except: 很容易隱藏真正的bug.盡量減少try/except塊中的代碼量. try塊的體積越大, 期望之外的異常就越容易被觸發(fā). 這種情況下, try/except塊將隱藏真正的錯誤.
使用finally子句來執(zhí)行那些無論try塊中有沒有異常都應該被執(zhí)行的代碼. 這對于清理資源常常很有用, 例如關閉文件.
當捕獲異常時, 使用 as 而不要用逗號.
避免全局變量
定義:定義在模塊級的變量.優(yōu)點:偶爾有用.缺點:導入時可能改變模塊行為, 因為導入模塊時會對模塊級變量賦值.結(jié)論:避免使用全局變量, 用類變量來代替. 但也有一些例外:
腳本的默認選項.
模塊級常量. 例如: PI = 3.14159. 常量應該全大寫, 用下劃線連接.
有時候用全局變量來緩存值或者作為函數(shù)返回值很有用.
如果需要, 全局變量應該僅在模塊內(nèi)部可用, 并通過模塊級的公共函數(shù)來訪問.
鼓勵使用嵌套/本地/內(nèi)部類或函數(shù)
定義:類可以定義在方法, 函數(shù)或者類中. 函數(shù)可以定義在方法或函數(shù)中. 封閉區(qū)間中定義的變量對嵌套函數(shù)是只讀的.優(yōu)點:允許定義僅用于有效范圍的工具類和函數(shù).缺點:嵌套類或局部類的實例不能序列化(pickled).結(jié)論:推薦使用.
可以在簡單情況下使用
定義:列表推導(list comprehensions)與生成器表達式(generator expression)提供了一種簡潔高效的方式來創(chuàng)建列表和迭代器, 而不必借助map(), filter(), 或者lambda.優(yōu)點:簡單的列表推導可以比其它的列表創(chuàng)建方法更加清晰簡單. 生成器表達式可以十分高效, 因為它們避免了創(chuàng)建整個列表.缺點:復雜的列表推導或者生成器表達式可能難以閱讀.結(jié)論:適用于簡單情況. 每個部分應該單獨置于一行: 映射表達式, for語句, 過濾器表達式. 禁止多重for語句或過濾器表達式. 復雜情況下還是使用循環(huán).
如果類型支持, 就使用默認迭代器和操作符. 比如列表, 字典及文件等.
定義:容器類型, 像字典和列表, 定義了默認的迭代器和關系測試操作符(in和not in)優(yōu)點:默認操作符和迭代器簡單高效, 它們直接表達了操作, 沒有額外的方法調(diào)用. 使用默認操作符的函數(shù)是通用的. 它可以用于支持該操作的任何類型.缺點:你沒法通過閱讀方法名來區(qū)分對象的類型(例如, has_key()意味著字典). 不過這也是優(yōu)點.結(jié)論:如果類型支持, 就使用默認迭代器和操作符, 例如列表, 字典和文件. 內(nèi)建類型也定義了迭代器方法. 優(yōu)先考慮這些方法, 而不是那些返回列表的方法. 當然，這樣遍歷容器時，你將不能修改容器.
按需使用生成器.
定義:所謂生成器函數(shù), 就是每當它執(zhí)行一次生成(yield)語句, 它就返回一個迭代器, 這個迭代器生成一個值. 生成值后, 生成器函數(shù)的運行狀態(tài)將被掛起, 直到下一次生成.優(yōu)點:簡化代碼, 因為每次調(diào)用時, 局部變量和控制流的狀態(tài)都會被保存. 比起一次創(chuàng)建一系列值的函數(shù), 生成器使用的內(nèi)存更少.缺點:沒有.結(jié)論:鼓勵使用. 注意在生成器函數(shù)的文檔字符串中使用”Yields:”而不是”Returns:”.(譯者注: 參看 注釋 )
適用于單行函數(shù)
定義:與語句相反, lambda在一個表達式中定義匿名函數(shù). 常用于為 map() 和 filter() 之類的高階函數(shù)定義回調(diào)函數(shù)或者操作符.優(yōu)點:方便.缺點:比本地函數(shù)更難閱讀和調(diào)試. 沒有函數(shù)名意味著堆棧跟蹤更難理解. 由于lambda函數(shù)通常只包含一個表達式, 因此其表達能力有限.結(jié)論:適用于單行函數(shù). 如果代碼超過60-80個字符, 最好還是定義成常規(guī)(嵌套)函數(shù).對于常見的操作符，例如乘法操作符，使用 operator 模塊中的函數(shù)以代替lambda函數(shù). 例如, 推薦使用 operator.mul , 而不是 lambda x, y: x * y .
適用于單行函數(shù)
定義:條件表達式是對于if語句的一種更為簡短的句法規(guī)則. 例如: x = 1 if cond else 2 .優(yōu)點:比if語句更加簡短和方便.缺點:比if語句難于閱讀. 如果表達式很長， 難于定位條件.結(jié)論:適用于單行函數(shù). 在其他情況下，推薦使用完整的if語句.
適用于大部分情況.
定義:你可以在函數(shù)參數(shù)列表的最后指定變量的值, 例如, def foo(a, b = 0): . 如果調(diào)用foo時只帶一個參數(shù), 則b被設為0. 如果帶兩個參數(shù), 則b的值等于第二個參數(shù).優(yōu)點:你經(jīng)常會碰到一些使用大量默認值的函數(shù), 但偶爾(比較少見)你想要覆蓋這些默認值. 默認參數(shù)值提供了一種簡單的方法來完成這件事, 你不需要為這些罕見的例外定義大量函數(shù). 同時, Python也不支持重載方法和函數(shù), 默認參數(shù)是一種”仿造”重載行為的簡單方式.缺點:默認參數(shù)只在模塊加載時求值一次. 如果參數(shù)是列表或字典之類的可變類型, 這可能會導致問題. 如果函數(shù)修改了對象(例如向列表追加項), 默認值就被修改了.結(jié)論:鼓勵使用, 不過有如下注意事項:不要在函數(shù)或方法定義中使用可變對象作為默認值.
訪問和設置數(shù)據(jù)成員時, 你通常會使用簡單, 輕量級的訪問和設置函數(shù). 建議用屬性（properties）來代替它們.
定義:一種用于包裝方法調(diào)用的方式. 當運算量不大, 它是獲取和設置屬性(attribute)的標準方式.優(yōu)點:通過消除簡單的屬性(attribute)訪問時顯式的get和set方法調(diào)用, 可讀性提高了. 允許懶惰的計算. 用Pythonic的方式來維護類的接口. 就性能而言, 當直接訪問變量是合理的, 添加訪問方法就顯得瑣碎而無意義. 使用屬性(properties)可以繞過這個問題. 將來也可以在不破壞接口的情況下將訪問方法加上.缺點:屬性(properties)是在get和set方法聲明后指定, 這需要使用者在接下來的代碼中注意: set和get是用于屬性(properties)的(除了用 @property 裝飾器創(chuàng)建的只讀屬性). 必須繼承自object類. 可能隱藏比如操作符重載之類的副作用. 繼承時可能會讓人困惑.結(jié)論:你通常習慣于使用訪問或設置方法來訪問或設置數(shù)據(jù), 它們簡單而輕量. 不過我們建議你在新的代碼中使用屬性. 只讀屬性應該用 @property 裝飾器 來創(chuàng)建.如果子類沒有覆蓋屬性, 那么屬性的繼承可能看上去不明顯. 因此使用者必須確保訪問方法間接被調(diào)用, 以保證子類中的重載方法被屬性調(diào)用(使用模板方法設計模式).
(譯者注: 老實說, 我覺得這段示例代碼很不恰當, 有必要這么蛋疼嗎?)
盡可能使用隱式false
定義:Python在布爾上下文中會將某些值求值為false. 按簡單的直覺來講, 就是所有的”空”值都被認為是false. 因此0， None, [], {}, “” 都被認為是false.優(yōu)點:使用Python布爾值的條件語句更易讀也更不易犯錯. 大部分情況下, 也更快.缺點:對C/C++開發(fā)人員來說, 可能看起來有點怪.結(jié)論:盡可能使用隱式的false, 例如: 使用 if foo: 而不是 if foo != []: . 不過還是有一些注意事項需要你銘記在心:
永遠不要用==或者!=來比較單件, 比如None. 使用is或者is not.
注意: 當你寫下 if x: 時, 你其實表示的是 if x is not None . 例如: 當你要測試一個默認值是None的變量或參數(shù)是否被設為其它值. 這個值在布爾語義下可能是false!
永遠不要用==將一個布爾量與false相比較. 使用 if not x: 代替. 如果你需要區(qū)分false和None, 你應該用像 if not x and x is not None: 這樣的語句.
對于序列(字符串, 列表, 元組), 要注意空序列是false. 因此 if not seq: 或者 if seq: 比 if len(seq): 或 if not len(seq): 要更好.
處理整數(shù)時, 使用隱式false可能會得不償失(即不小心將None當做0來處理). 你可以將一個已知是整型(且不是len()的返回結(jié)果)的值與0比較.
注意‘0’(字符串)會被當做true.
盡可能使用字符串方法取代字符串模塊. 使用函數(shù)調(diào)用語法取代apply(). 使用列表推導, for循環(huán)取代filter(), map()以及reduce().
定義:當前版本的Python提供了大家通常更喜歡的替代品.結(jié)論:我們不使用不支持這些特性的Python版本, 所以沒理由不用新的方式.
推薦使用
定義:嵌套的Python函數(shù)可以引用外層函數(shù)中定義的變量, 但是不能夠?qū)λ鼈冑x值. 變量綁定的解析是使用詞法作用域, 也就是基于靜態(tài)的程序文本. 對一個塊中的某個名稱的任何賦值都會導致Python將對該名稱的全部引用當做局部變量, 甚至是賦值前的處理. 如果碰到global聲明, 該名稱就會被視作全局變量.一個使用這個特性的例子:
(譯者注: 這個例子有點詭異, 你應該這樣使用這個函數(shù): sum = get_adder(summand1)(summand2) )
優(yōu)點:通?？梢詭砀忧逦? 優(yōu)雅的代碼. 尤其會讓有經(jīng)驗的Lisp和Scheme(還有Haskell, ML等)程序員感到欣慰.缺點:可能導致讓人迷惑的bug. 例如下面這個依據(jù) PEP-0227 的例子:
因此 foo([1, 2, 3]) 會打印 1 2 3 3 , 不是 1 2 3 4 .
(譯者注: x是一個列表, for循環(huán)其實是將x中的值依次賦給i.這樣對i的賦值就隱式的發(fā)生了, 整個foo函數(shù)體中的i都會被當做局部變量, 包括bar()中的那個. 這一點與C++之類的靜態(tài)語言還是有很大差別的.)
結(jié)論:鼓勵使用.
如果好處很顯然, 就明智而謹慎的使用裝飾器
定義:用于函數(shù)及方法的裝飾器 (也就是@標記). 最常見的裝飾器是@classmethod 和@staticmethod, 用于將常規(guī)函數(shù)轉(zhuǎn)換成類方法或靜態(tài)方法. 不過, 裝飾器語法也允許用戶自定義裝飾器. 特別地, 對于某個函數(shù) my_decorator , 下面的兩段代碼是等效的:
pydoc 或其它工具導入). 應該保證一個用有效參數(shù)調(diào)用的裝飾器在所有情況下都是成功的.裝飾器是一種特殊形式的”頂級代碼”. 參考后面關于 Main 的話題.不要依賴內(nèi)建類型的原子性.
雖然Python的內(nèi)建類型例如字典看上去擁有原子操作, 但是在某些情形下它們?nèi)匀徊皇窃拥?即: 如果__hash__或__eq__被實現(xiàn)為Python方法)且它們的原子性是靠不住的. 你也不能指望原子變量賦值(因為這個反過來依賴字典).
優(yōu)先使用Queue模塊的 Queue 數(shù)據(jù)類型作為線程間的數(shù)據(jù)通信方式. 另外, 使用threading模塊及其鎖原語(locking primitives). 了解條件變量的合適使用方式, 這樣你就可以使用 threading.Condition 來取代低級別的鎖了.
避免使用這些特性
定義:Python是一種異常靈活的語言, 它為你提供了很多花哨的特性, 諸如元類(metaclasses), 字節(jié)碼訪問, 任意編譯(on-the-fly compilation), 動態(tài)繼承, 對象父類重定義(object reparenting), 導入黑客(import hacks), 反射, 系統(tǒng)內(nèi)修改(modification of system internals), 等等.優(yōu)點:強大的語言特性, 能讓你的代碼更緊湊.缺點:使用這些很”酷”的特性十分誘人, 但不是絕對必要. 使用奇技淫巧的代碼將更加難以閱讀和調(diào)試. 開始可能還好(對原作者而言), 但當你回顧代碼, 它們可能會比那些稍長一點但是很直接的代碼更加難以理解.結(jié)論:在你的代碼中避免這些特性.
不要在行尾加分號, 也不要用分號將兩條命令放在同一行.
每行不超過80個字符
例外:
長的導入模塊語句
注釋里的URL
不要使用反斜杠連接行.
Python會將 圓括號, 中括號和花括號中的行隱式的連接起來 , 你可以利用這個特點. 如果需要, 你可以在表達式外圍增加一對額外的圓括號.
如果一個文本字符串在一行放不下, 可以使用圓括號來實現(xiàn)隱式行連接:
在注釋中，如果必要，將長的URL放在一行上。
注意上面例子中的元素縮進; 你可以在本文的 縮進 部分找到解釋.
寧缺毋濫的使用括號
除非是用于實現(xiàn)行連接, 否則不要在返回語句或條件語句中使用括號. 不過在元組兩邊使用括號是可以的.
用4個空格來縮進代碼
絕對不要用tab, 也不要tab和空格混用. 對于行連接的情況, 你應該要么垂直對齊換行的元素(見 行長度 部分的示例), 或者使用4空格的懸掛式縮進(這時第一行不應該有參數(shù)):
頂級定義之間空兩行, 方法定義之間空一行
頂級定義之間空兩行, 比如函數(shù)或者類定義. 方法定義, 類定義與第一個方法之間, 都應該空一行. 函數(shù)或方法中, 某些地方要是你覺得合適, 就空一行.
按照標準的排版規(guī)范來使用標點兩邊的空格
括號內(nèi)不要有空格.
不要在逗號, 分號, 冒號前面加空格, 但應該在它們后面加(除了在行尾).
參數(shù)列表, 索引或切片的左括號前不應加空格.
在二元操作符兩邊都加上一個空格, 比如賦值(=), 比較(==, <,>, !=, <>, <=,>=, in, not in, is, is not), 布爾(and, or, not). 至于算術操作符兩邊的空格該如何使用, 需要你自己好好判斷. 不過兩側(cè)務必要保持一致.
當’=’用于指示關鍵字參數(shù)或默認參數(shù)值時, 不要在其兩側(cè)使用空格.
不要用空格來垂直對齊多行間的標記, 因為這會成為維護的負擔(適用于:, #, =等):
大部分.py文件不必以#!作為文件的開始. 根據(jù) PEP-394 , 程序的main文件應該以 #!/usr/bin/python2或者 #!/usr/bin/python3開始.
(譯者注: 在計算機科學中, Shebang (也稱為Hashbang)是一個由井號和嘆號構成的字符串行(#!), 其出現(xiàn)在文本文件的第一行的前兩個字符. 在文件中存在Shebang的情況下, 類Unix操作系統(tǒng)的程序載入器會分析Shebang后的內(nèi)容, 將這些內(nèi)容作為解釋器指令, 并調(diào)用該指令, 并將載有Shebang的文件路徑作為該解釋器的參數(shù). 例如, 以指令#!/bin/sh開頭的文件在執(zhí)行時會實際調(diào)用/bin/sh程序.)
#!先用于幫助內(nèi)核找到Python解釋器, 但是在導入模塊時, 將會被忽略. 因此只有被直接執(zhí)行的文件中才有必要加入#!.
確保對模塊, 函數(shù), 方法和行內(nèi)注釋使用正確的風格
文檔字符串
Python有一種獨一無二的的注釋方式: 使用文檔字符串. 文檔字符串是包, 模塊, 類或函數(shù)里的第一個語句. 這些字符串可以通過對象的__doc__成員被自動提取, 并且被pydoc所用. (你可以在你的模塊上運行pydoc試一把, 看看它長什么樣). 我們對文檔字符串的慣例是使用三重雙引號”“”( PEP-257 ). 一個文檔字符串應該這樣組織: 首先是一行以句號, 問號或驚嘆號結(jié)尾的概述(或者該文檔字符串單純只有一行). 接著是一個空行. 接著是文檔字符串剩下的部分, 它應該與文檔字符串的第一行的第一個引號對齊. 下面有更多文檔字符串的格式化規(guī)范.
模塊
每個文件應該包含一個許可樣板. 根據(jù)項目使用的許可(例如, Apache 2.0, BSD, LGPL, GPL), 選擇合適的樣板.
函數(shù)和方法
下文所指的函數(shù),包括函數(shù), 方法, 以及生成器.
一個函數(shù)必須要有文檔字符串, 除非它滿足以下條件:
外部不可見
非常短小
簡單明了
文檔字符串應該包含函數(shù)做什么, 以及輸入和輸出的詳細描述. 通常, 不應該描述”怎么做”, 除非是一些復雜的算法. 文檔字符串應該提供足夠的信息, 當別人編寫代碼調(diào)用該函數(shù)時, 他不需要看一行代碼, 只要看文檔字符串就可以了. 對于復雜的代碼, 在代碼旁邊加注釋會比使用文檔字符串更有意義.
關于函數(shù)的幾個方面應該在特定的小節(jié)中進行描述記錄， 這幾個方面如下文所述. 每節(jié)應該以一個標題行開始. 標題行以冒號結(jié)尾. 除標題行外, 節(jié)的其他內(nèi)容應被縮進2個空格.
Args:列出每個參數(shù)的名字, 并在名字后使用一個冒號和一個空格, 分隔對該參數(shù)的描述.如果描述太長超過了單行80字符,使用2或者4個空格的懸掛縮進(與文件其他部分保持一致). 描述應該包括所需的類型和含義. 如果一個函數(shù)接受*foo(可變長度參數(shù)列表)或者**bar (任意關鍵字參數(shù)), 應該詳細列出*foo和**bar.Returns: (或者 Yields: 用于生成器)描述返回值的類型和語義. 如果函數(shù)返回None, 這一部分可以省略.Raises:列出與接口有關的所有異常.
類
類應該在其定義下有一個用于描述該類的文檔字符串. 如果你的類有公共屬性(Attributes), 那么文檔中應該有一個屬性(Attributes)段. 并且應該遵守和函數(shù)參數(shù)相同的格式.
塊注釋和行注釋
最需要寫注釋的是代碼中那些技巧性的部分. 如果你在下次 代碼審查 的時候必須解釋一下, 那么你應該現(xiàn)在就給它寫注釋. 對于復雜的操作, 應該在其操作開始前寫上若干行注釋. 對于不是一目了然的代碼, 應在其行尾添加注釋.
為了提高可讀性, 注釋應該至少離開代碼2個空格.
另一方面, 絕不要描述代碼. 假設閱讀代碼的人比你更懂Python, 他只是不知道你的代碼要做什么.
如果一個類不繼承自其它類, 就顯式的從object繼承. 嵌套類也一樣.
繼承自 object 是為了使屬性(properties)正常工作, 并且這樣可以保護你的代碼, 使其不受 PEP-3000 的一個特殊的潛在不兼容性影響. 這樣做也定義了一些特殊的方法, 這些方法實現(xiàn)了對象的默認語義, 包括 __new__, __init__, __delattr__, __getattribute__, __setattr__, __hash__, __repr__, and __str__ .
即使參數(shù)都是字符串, 使用%操作符或者格式化方法格式化字符串. 不過也不能一概而論, 你需要在+和%之間好好判定.
避免在循環(huán)中用+和+=操作符來累加字符串. 由于字符串是不可變的, 這樣做會創(chuàng)建不必要的臨時對象, 并且導致二次方而不是線性的運行時間. 作為替代方案, 你可以將每個子串加入列表, 然后在循環(huán)結(jié)束后用 .join 連接列表. (也可以將每個子串寫入一個 cStringIO.StringIO 緩存中.)
在同一個文件中, 保持使用字符串引號的一致性. 使用單引號’或者雙引號”之一用以引用字符串, 并在同一文件中沿用. 在字符串內(nèi)可以使用另外一種引號, 以避免在字符串中使用. GPyLint已經(jīng)加入了這一檢查.
(譯者注:GPyLint疑為筆誤, 應為PyLint.)
為多行字符串使用三重雙引號”“”而非三重單引號’‘’. 當且僅當項目中使用單引號’來引用字符串時, 才可能會使用三重’‘’為非文檔字符串的多行字符串來標識引用. 文檔字符串必須使用三重雙引號”“”. 不過要注意, 通常用隱式行連接更清晰, 因為多行字符串與程序其他部分的縮進方式不一致.
在文件和sockets結(jié)束時, 顯式的關閉它.
除文件外, sockets或其他類似文件的對象在沒有必要的情況下打開, 會有許多副作用, 例如:
它們可能會消耗有限的系統(tǒng)資源, 如文件描述符. 如果這些資源在使用后沒有及時歸還系統(tǒng), 那么用于處理這些對象的代碼會將資源消耗殆盡.
持有文件將會阻止對于文件的其他諸如移動、刪除之類的操作.
僅僅是從邏輯上關閉文件和sockets, 那么它們?nèi)匀豢赡軙黄涔蚕淼某绦蛟跓o意中進行讀或者寫操作. 只有當它們真正被關閉后, 對于它們嘗試進行讀或者寫操作將會跑出異常, 并使得問題快速顯現(xiàn)出來.
而且, 幻想當文件對象析構時, 文件和sockets會自動關閉, 試圖將文件對象的生命周期和文件的狀態(tài)綁定在一起的想法, 都是不現(xiàn)實的. 因為有如下原因:
沒有任何方法可以確保運行環(huán)境會真正的執(zhí)行文件的析構. 不同的Python實現(xiàn)采用不同的內(nèi)存管理技術, 比如延時垃圾處理機制. 延時垃圾處理機制可能會導致對象生命周期被任意無限制的延長.
對于文件意外的引用,會導致對于文件的持有時間超出預期(比如對于異常的跟蹤, 包含有全局變量等).
推薦使用 “with”語句 以管理文件:
對于不支持使用”with”語句的類似文件的對象,使用 contextlib.closing():
Legacy AppEngine 中Python 2.5的代碼如使用”with”語句, 需要添加 “from __future__ import with_statement”.
為臨時代碼使用TODO注釋, 它是一種短期解決方案. 不算完美, 但夠好了.
TODO注釋應該在所有開頭處包含”TODO”字符串, 緊跟著是用括號括起來的你的名字, email地址或其它標識符. 然后是一個可選的冒號. 接著必須有一行注釋, 解釋要做什么. 主要目的是為了有一個統(tǒng)一的TODO格式, 這樣添加注釋的人就可以搜索到(并可以按需提供更多細節(jié)). 寫了TODO注釋并不保證寫的人會親自解決問題. 當你寫了一個TODO, 請注上你的名字.
如果你的TODO是”將來做某事”的形式, 那么請確保你包含了一個指定的日期(“2009年11月解決”)或者一個特定的事件(“等到所有的客戶都可以處理XML請求就移除這些代碼”).
每個導入應該獨占一行
導入總應該放在文件頂部, 位于模塊注釋和文檔字符串之后, 模塊全局變量和常量之前. 導入應該按照從最通用到最不通用的順序分組:
標準庫導入
第三方庫導入
應用程序指定導入
每種分組中, 應該根據(jù)每個模塊的完整包路徑按字典序排序, 忽略大小寫.
通常每個語句應該獨占一行
不過, 如果測試結(jié)果與測試語句在一行放得下, 你也可以將它們放在同一行. 如果是if語句, 只有在沒有else時才能這樣做. 特別地, 絕不要對 try/except 這樣做, 因為try和except不能放在同一行.
在Python中, 對于瑣碎又不太重要的訪問函數(shù), 你應該直接使用公有變量來取代它們, 這樣可以避免額外的函數(shù)調(diào)用開銷. 當添加更多功能時, 你可以用屬性(property)來保持語法的一致性.
(譯者注: 重視封裝的面向?qū)ο蟪绦騿T看到這個可能會很反感, 因為他們一直被教育: 所有成員變量都必須是私有的! 其實, 那真的是有點麻煩啊. 試著去接受Pythonic哲學吧)
另一方面, 如果訪問更復雜, 或者變量的訪問開銷很顯著, 那么你應該使用像 get_foo() 和 set_foo()這樣的函數(shù)調(diào)用. 如果之前的代碼行為允許通過屬性(property)訪問 , 那么就不要將新的訪問函數(shù)與屬性綁定. 這樣, 任何試圖通過老方法訪問變量的代碼就沒法運行, 使用者也就會意識到復雜性發(fā)生了變化.
module_name, package_name, ClassName, method_name, ExceptionName, function_name, GLOBAL_VAR_NAME, instance_var_name, function_parameter_name, local_var_name.
應該避免的名稱
單字符名稱, 除了計數(shù)器和迭代器.
包/模塊名中的連字符(-)
雙下劃線開頭并結(jié)尾的名稱(Python保留, 例如__init__)
命名約定
所謂”內(nèi)部(Internal)”表示僅模塊內(nèi)可用, 或者, 在類內(nèi)是保護或私有的.
用單下劃線(_)開頭表示模塊變量或函數(shù)是protected的(使用import * from時不會包含).
用雙下劃線(__)開頭的實例變量或方法表示類內(nèi)私有.
將相關的類和頂級函數(shù)放在同一個模塊里. 不像Java, 沒必要限制一個類一個模塊.
對類名使用大寫字母開頭的單詞(如CapWords, 即Pascal風格), 但是模塊名應該用小寫加下劃線的方式(如lower_with_under.py). 盡管已經(jīng)有很多現(xiàn)存的模塊使用類似于CapWords.py這樣的命名, 但現(xiàn)在已經(jīng)不鼓勵這樣做, 因為如果模塊名碰巧和類名一致, 這會讓人困擾.
Python之父Guido推薦的規(guī)范
即使是一個打算被用作腳本的文件, 也應該是可導入的. 并且簡單的導入不應該導致這個腳本的主功能(main functionality)被執(zhí)行, 這是一種副作用. 主功能應該放在一個main()函數(shù)中.
在Python中, pydoc以及單元測試要求模塊必須是可導入的. 你的代碼應該在執(zhí)行主程序前總是檢查 if __name__ == '__main__' , 這樣當模塊被導入時主程序就不會被執(zhí)行.
所有的頂級代碼在模塊導入時都會被執(zhí)行. 要小心不要去調(diào)用函數(shù), 創(chuàng)建對象, 或者執(zhí)行那些不應該在使用pydoc時執(zhí)行的操作.
