Python編碼規(guī)范

1、Python編碼規(guī)范目錄(TABLE OF CONTENTS)1.介紹這篇文檔所給出的編碼約定適用于在主要的Python發(fā)布版本中組成標準庫的Python代碼，請查閱相關(guān)的關(guān)于在Python的C實現(xiàn)中C代碼風格指南的描述。2.版權(quán)聲明這篇文檔改編自Guido最初的Python風格指南一文，并從Barrys style guide中添加了部分內(nèi)容。在有沖突的地方，Guide的風格規(guī)則應該是符合本PEP的意圖。這篇PEP仍然尚未完成(實際上，它可能永遠都不會完成)。3.一致性建議在這篇風格指導中的一致性是重要的。在一個項目內(nèi)的一致性更重要。在一個模塊或函數(shù)內(nèi)的一致性最重要。但最重要的是:知道何時會

2、不一致有時只是沒有實施風格指導。當出現(xiàn)疑惑時，運用你的最佳判斷，看看別的例子，然后決定怎樣看起來更好。并且要不恥下問！打破一條既定規(guī)則的兩個好理由:一、 當應用這個規(guī)則是將導致代碼可讀性下降，即便對某人來說，他已經(jīng)習慣于按這條規(guī)則來閱讀代碼了。二、為了和周圍的代碼保持一致而打破規(guī)則(也許是歷史原因)，雖然這也是個清除其它混亂的好機會(真正的XP風格)。4.代碼的布局4.1.縮進4個空格一個縮進層次。對于確實古老的代碼，你不希望產(chǎn)生混亂，可以繼續(xù)使用8空格的制表符(8-space tabs)。Emacs Python-mode自動發(fā)現(xiàn)文件中主要的縮進層次，依此設(shè)定縮進參數(shù)。4.2.制表符還是空格

3、Python 依賴縮進來確定代碼塊的層次，行首空白符主要有兩種：tab 和空格，但嚴禁兩者混用。如果使用 tab 縮進，設(shè)定 tab 為 4 個空格。公司內(nèi)部推薦使用 4 個空格的 tab 進行縮進。4.3.行的最大長度周圍仍然有許多設(shè)備被限制在每行80字符；而且，窗口限制在80個字符。使將多個窗口并排放置成為可能。在這些設(shè)備上使用默認的折疊方式看起來有點丑陋。因此，請將所有行限制在最大79字符(Emacs準確得將行限制為長80字符)，對順序排放的大塊文本(文檔字符串或注釋)，推薦將長度限制在72字符。折疊長行的首選方法是使用Pyhon支持的圓括號，方括號和花括號內(nèi)的行延續(xù)。如果需要，你可以在

4、表達式周圍增加一對額外的圓括號，但是有時使用反斜杠看起來更好，確認恰當?shù)每s進了延續(xù)的行。一些例子:圖14.4.空行適當?shù)目招杏欣谠黾哟a的可讀性，加空行可以參考如下幾個準則：一、在類、函數(shù)的定義間加空行；二、在 import 不同種類的模塊間加空行；三、在函數(shù)中的邏輯段落間加空行，即把相關(guān)的代碼緊湊寫在一起，作為一個邏輯段落，段落間以空行分隔；4.5.編碼Python腳本可以通過在文件頭上加“#-*- coding: xxx -*-”來設(shè)置編輯器默認保存的編碼格式。例如：#-*- coding: utf-8 -*-。5.導入通常應該在單獨的行中導入(Imports)，例如:圖2但是這樣也是可

5、以的:圖3Imports 通常被放置在文件的頂部，僅在模塊注釋和文檔字符串之后，在模塊的全局變量和常量之前。Imports應該有順序地成組安放:一、標準庫的導入(Imports )，即Python內(nèi)置模塊。二、相關(guān)的主包(major package)的導入，即第三方模塊。三、特定應用的導入(imports)，即自己開發(fā)的模塊。你應該在每組導入之間放置一個空行，對于內(nèi)部包的導入是不推薦使用相對導入的，對所有導入都要使用包的絕對路徑。從一個包含類的模塊中導入類時，通?？梢詫懗蛇@樣:圖4如果這樣寫導致了本地名字沖突，那么就這樣寫:圖5即使用MyClass.MyClass和foo.bar.YourCl

6、ass.YourClass。6.表達式和語句中的空格緊挨著圓括號，方括號和花括號的，如:圖6緊貼在逗號，分號或冒號前的，如:圖7緊貼著函數(shù)調(diào)用的參數(shù)列表前開式括號(open parenthesis )的，如:圖8緊貼在索引或切片，開始的開式括號前的，如:圖9在賦值(或其它)運算符周圍的用于和其它并排的一個以上的空格，如:圖106.1.其它建議始終在這些二元運算符兩邊放置一個空格:賦值(=)， 比較(=，!=，=，=，in，not in，is，is not)，布爾運算 (and，or，not)。按你的看法在算術(shù)運算符周圍插入空格。 始終保持二元運算符兩邊空格的一致一些例子:圖11不要在用于指定關(guān)

7、鍵字參數(shù)或默認參數(shù)值的=號周圍使用空格，例如:圖12不要將多條語句寫在同一行上:圖137.注釋同代碼不一致的注釋比沒注釋更差。當代碼修改時，始終優(yōu)先更新注釋!注釋應該是完整的句子，如果注釋是一個短語或句子，首字母應該大寫，除非他是一個以小寫字母開頭的標識符(永遠不要修改標識符的大小寫)。如果注釋很短，最好省略末尾的句號。注釋塊通常由一個或多個由完整句子構(gòu)成的段落組成，每個句子應該以句號結(jié)尾。你應該在句末，句號后使用兩個空格，以便使Emacs的斷行和填充工作協(xié)調(diào)一致。用英語書寫時，斷詞和空格是可用的。非英語國家的Python程序員:請用英語書寫你的注釋，除非你120%的確信這些代碼不會被不懂你的

8、語言的人閱讀。7.1.注釋塊注釋塊通常應用于跟隨著一些(或者全部)代碼并和這些代碼有著相同的縮進層次。注釋塊中每行以#和一個空格開始(除非他是注釋內(nèi)的縮進文本)。注釋塊內(nèi)的段落以僅含單個#的行分割。注釋塊上下方最好有一空行包圍(或上方兩行下方一行，對一個新函數(shù)定義段的注釋)。7.2.行內(nèi)注釋一個行內(nèi)注釋是和語句在同一行的注釋，行內(nèi)注釋應該謹慎適用，行內(nèi)注釋應該至少用兩個空格和語句分開，它們應該以#和單個空格開始:圖14如果語意是很明了的，那么行內(nèi)注釋是不必要的，事實上是應該被移除的。不要這樣寫:圖15但是有時，這樣是有益的:圖168.文檔化為所有公共模塊，函數(shù)，類和方法編寫文檔字符串。文檔字符

9、串對非公開的方法不是必要的，但你應該有一個描述這個方法做什么的注釋。這個注釋應該在def這行后。PEP 257 描述了好的文檔字符串的約定。一定注意，多行文檔字符串結(jié)尾的應該單獨成行，例如:圖179.版本注記如果你要將RCS或CVS的雜項(crud)包含在你的源文件中，按如下做:圖18這個行應該包含在模塊的文檔字符串之后，所有代碼之前，上下用一個空行分割。10.命名約定Python庫的命名約定有點混亂，所以我們將永遠不能使之變得完全一致，不過還是有公認的命名規(guī)范的。新的模塊和包(包括第三方的框架)必須符合這些標準，但對已有的庫存在不同風格的，保持內(nèi)部的一致性是首選的。10.1.描述:命名風格有

10、許多不同的命名風格。以下的有助于辨認正在使用的命名風格，獨立于它們的作用。以下的命名風格是眾所周知的:- b (單個小寫字母)- B (單個大寫字母)- Lowercase（小寫）- lower_case_with_underscores（有下劃線的小寫）- UPPERCASE（大寫）- UPPER_CASE_WITH_UNDERSCORES（有下劃線的大寫）- CapitalizedWords (或 CapWords，CamelCase這樣命名是因為可從字母的大小寫分出單詞。這有時也被當作StudlyCaps。- mixedCase (與CapitalizedWords的不同在于首字母小寫!

11、)- Capitalized_Words_With_Underscores（有下劃線的首字母大寫）還有用短的特別前綴將相關(guān)的名字聚合在一起的風格。這在Python中不常用，但是出于完整性要提一下，例如，os.stat()函數(shù)返回一個元組，他的元素傳統(tǒng)上說名如st_mode， st_size，st_mtime等等。X11庫的所有公開函數(shù)以X開頭。(在Python中，這個風格通常認為是不必要的，因為屬性和方法名以對象作前綴，而函數(shù)名以模塊名作前綴。)另外，以下用下劃線作前導或結(jié)尾的特殊形式是被公認的(這些通?？梢院腿魏瘟晳T組合):- _single_leading_underscore(單個下劃線

12、作前導):弱的“內(nèi)部使用(internal use)”標志，例如，“from M import *”不會導入以下劃線開頭的對象。- single_trailing_underscore_(單個下劃線結(jié)尾): 用于避免與Python關(guān)鍵詞的沖突，例如:“Tkinter.Toplevel(master，class_=ClassName)”。- _double_leading_underscore(雙下劃線):從Python 1.4起為類私有名。- _double_leading_and_trailing_underscore_:“magic”對象或?qū)傩?，存在于用戶控制?user-controll

13、ed)名字空間，例如:_init_， _import_ 或_file_。有時它們被用戶定義用于觸發(fā)某個魔法行為(例如:運算符重載):有時被構(gòu)造器插入，以便自己使用或為了調(diào)試。因此，在未來的版本中，構(gòu)造器(松散得定義為Python解釋器和標準庫)可能打算建立自己的魔法屬性列表，用戶代碼通常應該限制將這種約定作為己用。欲成為構(gòu)造器的一部分的用戶代碼可以在下滑線中結(jié)合使用短前綴，例如:_bobo_magic_attr_。10.2.說明:命名約定一致的命名可以給開發(fā)人員減少許多麻煩，而恰如其分的命名則可以大幅提高代碼的可讀性，降低維護成本。10.2.1.常量名常量名所有字母大寫，由下劃線連接各個單詞，

14、例如：圖1910.2.2.變量名變量名全部小寫，由下劃線連接各個單詞，例如：圖20不論是類成員變量還是全局變量，均不使用 m 或 g 前綴。私有類成員使用單一下劃線前綴標識，多定義公開成員，少定義私有成員。變量名不應帶有類型信息，因為 Python 是動態(tài)類型語言。如 iValue、names_list、dict_obj 等都是不好的命名。10.2.3.函數(shù)名函數(shù)名的命名規(guī)則與變量名相同。例如：圖2110.2.4.類名類名單詞首字母大寫，不使用下劃線連接單詞，也不加入 C、T 等前綴。例如：圖2210.2.5.模塊名模塊名全部小寫，對于包內(nèi)使用的模塊，可以加一個下劃線前綴，例如：圖2310.2

15、.6.包名包的命名規(guī)范與模塊相同。10.2.7.縮寫命名應當盡量使用全拼寫的單詞，縮寫的情況有如下兩種：常用的縮寫，如 XML、ID等，在命名時也應只大寫首字母，例如：圖24命名中含有長單詞，對某個單詞進行縮寫。這時應使用約定成俗的縮寫方式，如去除元音、包含輔音的首字符等方式，例如：圖2510.2.8.特定的命名方式主要是指 _xxx_ 形式的系統(tǒng)保留字命名法。項目中也可以使用這種命名，它的意義在于這種形式的變量是只讀的，這種形式的類成員函數(shù)盡量不要重載。例如：圖26其中 _id_、_parent_ 和 _message_ 都采用了系統(tǒng)保留字命名法。11.設(shè)計建議單個元素(singletons

16、)的比較，如None 應該永遠用:is或is not來做。當你本意是“if x is not None”時，對寫成“if x”要小心。例如當你測試一個默認為None的變量或參數(shù)是否被設(shè)置為其它值時，這個值也許在布爾上下文(Boolean context)中是false！基于類的異?？偸呛眠^基于字符串的異常。模塊和包應該定義它們自己的域內(nèi)特定的基異常類，基類應該是內(nèi)建的Exception類子類。還始終包含一個類的文檔字符串。例如:圖27使用字符串方法(methods)代替字符串模塊，除非必須向后兼容Python 2.0以前的版本。字符串方法總是非常快，而且和unicode字符串共用同樣的API(

17、應用程序接口)在檢查前綴或后綴時避免對字符串進行切片。用startswith()和endswith()代替，因為它們是明確的并且錯誤更少。例如:圖28例外是如果你的代碼必須工作在Python 1.5.2 (但是我們希望它不會發(fā)生！)，對象類型的比較應該始終用isinstance()代替直接比較類型，例如:圖29檢查一個對象是否是字符串時，緊記它也可能是unicode字符串！在Python 2.3，str和unicode有公共的基類，basestring，所以你可以這樣做:圖30在Python 2.2類型模塊為此定義了StringTypes類型，例如:圖31在Python 2.0和2.1，你應該

18、這樣做:圖32對序列，(字符串，列表，元組)，使用空列表是false這個事實，因此“if not seq”或“if seq”比“if len(seq)”或“if not len(seq)”好。書寫字符串文字時不要依賴于有意義的后置空格。這種后置空格在視覺上是不可辨別的，并且有些編輯器(特別是近來，reindent.py)會將它們修整掉。不要用=來比較布爾型的值以確定是True或False(布爾型是Pythn 2.3中新增的):圖33對于條件和循環(huán)語句，不要寫成一行，否則不是好的代碼，例如：圖3412.已有代碼對于項目中已有的代碼，可能因為歷史遺留原因不符合本規(guī)范，應當看作可以容忍的特例，允許存在；但不應