Python編碼規(guī)范

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

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

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

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

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

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

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

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

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

10、許多不同的命名風(fēng)格。以下的有助于辨認(rèn)正在使用的命名風(fēng)格，獨(dú)立于它們的作用。以下的命名風(fēng)格是眾所周知的:- b (單個(gè)小寫字母)- B (單個(gè)大寫字母)- Lowercase（小寫）- lower_case_with_underscores（有下劃線的小寫）- UPPERCASE（大寫）- UPPER_CASE_WITH_UNDERSCORES（有下劃線的大寫）- CapitalizedWords (或 CapWords，CamelCase這樣命名是因?yàn)榭蓮淖帜傅拇笮懛殖鰡卧~。這有時(shí)也被當(dāng)作StudlyCaps。- mixedCase (與CapitalizedWords的不同在于首字母小寫!

11、)- Capitalized_Words_With_Underscores（有下劃線的首字母大寫）還有用短的特別前綴將相關(guān)的名字聚合在一起的風(fēng)格。這在Python中不常用，但是出于完整性要提一下，例如，os.stat()函數(shù)返回一個(gè)元組，他的元素傳統(tǒng)上說名如st_mode， st_size，st_mtime等等。X11庫的所有公開函數(shù)以X開頭。(在Python中，這個(gè)風(fēng)格通常認(rèn)為是不必要的，因?yàn)閷傩院头椒詫ο笞髑熬Y，而函數(shù)名以模塊名作前綴。)另外，以下用下劃線作前導(dǎo)或結(jié)尾的特殊形式是被公認(rèn)的(這些通?？梢院腿魏瘟?xí)慣組合):- _single_leading_underscore(單個(gè)下劃線

12、作前導(dǎo)):弱的“內(nèi)部使用(internal use)”標(biāo)志，例如，“from M import *”不會(huì)導(dǎo)入以下劃線開頭的對象。- single_trailing_underscore_(單個(gè)下劃線結(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_。有時(shí)它們被用戶定義用于觸發(fā)某個(gè)魔法行為(例如:運(yùn)算符重載):有時(shí)被構(gòu)造器插入，以便自己使用或?yàn)榱苏{(diào)試。因此，在未來的版本中，構(gòu)造器(松散得定義為Python解釋器和標(biāo)準(zhǔn)庫)可能打算建立自己的魔法屬性列表，用戶代碼通常應(yīng)該限制將這種約定作為己用。欲成為構(gòu)造器的一部分的用戶代碼可以在下滑線中結(jié)合使用短前綴，例如:_bobo_magic_attr_。10.2.說明:命名約定一致的命名可以給開發(fā)人員減少許多麻煩，而恰如其分的命名則可以大幅提高代碼的可讀性，降低維護(hù)成本。10.2.1.常量名常量名所有字母大寫，由下劃線連接各個(gè)單詞，

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

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

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

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

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