Python 編程規(guī)范.doc

Python 編程規(guī)范編碼 所有的 Python 腳本文件都應(yīng)在文件頭標(biāo)上 # -*- coding:utf-8 -*- 。設(shè)置編輯器，默認(rèn)保存為 utf-8 格式。注釋 業(yè)界普遍認(rèn)同 Python 的注釋分為兩種的概念，一種是由 # 開頭的“真正的”注釋，另一種是 docstrings。前者表明為何選擇當(dāng)前實(shí)現(xiàn)以及這種實(shí)現(xiàn)的原理和難點(diǎn)，后者表明如何使用這個(gè)包、模塊、類、函數(shù)（方法），甚至包括使用示例和單元測試。 堅(jiān)持適當(dāng)注釋原則。對(duì)不存在技術(shù)難點(diǎn)的代碼堅(jiān)持不注釋，對(duì)存在技術(shù)難點(diǎn)的代碼必須注釋。但與注釋不同，推薦對(duì)每一個(gè)包、模塊、類、函數(shù)（方法）寫 docstrings，除非代碼一目了然，非常簡單?？s進(jìn) Python 依賴縮進(jìn)來確定代碼塊的層次，行首空白符主要有兩種：tab 和空格，但嚴(yán)禁兩者混用。如果使用 tab 縮進(jìn)，設(shè)定 tab 為 4 個(gè)空格。 公司內(nèi)部推薦使用 4 個(gè)空格的 tab 進(jìn)行縮進(jìn)。空格 空格在 Python 代碼中是有意義的，因?yàn)?Python 的語法依賴于縮進(jìn)，在行首的空格稱為前導(dǎo)空格。在這一節(jié)不討論前導(dǎo)空格相關(guān)的內(nèi)容，只討論非前導(dǎo)空格。非前導(dǎo)空格在 Python 代碼中沒有意義，但適當(dāng)?shù)丶尤敕乔皩?dǎo)空格可以增進(jìn)代碼的可讀性。1）在二元算術(shù)、邏輯運(yùn)算符前后加空格：如 a = b + c；2）在一元前綴運(yùn)算符后不加空格，如 if !flg: pass；3）“:”用在行尾時(shí)前后皆不加空格，如分枝、循環(huán)、函數(shù)和類定義語言；用在非行尾時(shí)兩端加空格，如 dict 對(duì)象的定義 d = key : value。4）括號(hào)（含圓括號(hào)、方括號(hào)和花括號(hào)）前后不加空格，如 do_something(arg1, arg2)，而不是 do_something( arg1, arg2 )；5）逗號(hào)后面加一個(gè)空格，前面不加空格；s空行 適當(dāng)?shù)目招杏欣谠黾哟a的可讀性，加空行可以參考如下幾個(gè)準(zhǔn)則：1）在類、函數(shù)的定義間加空行；2）在 import 不同種類的模塊間加工行；3）在函數(shù)中的邏輯段落間加空行，即把相關(guān)的代碼緊湊寫在一起，作為一個(gè)邏輯段落，段落間以空行分隔；斷行 盡管現(xiàn)在的寬屏顯示器已經(jīng)可以單屏顯示超過 256 列字符，但本規(guī)范仍然堅(jiān)持行的最大長度不得超過 78 個(gè)字符的標(biāo)準(zhǔn)。折疊長行的方法有以下幾種方法：1)為長變量名換一個(gè)短名，如： this.is.a.very.long.variable_name = this.is.another.long.variable_name 應(yīng)改為： variable_name1 = this.is.a.very.long.variable_name variable_name2 = this.is.another.variable_name variable_name1 = variable_name2s2)在括號(hào)（包括圓括號(hào)、方括號(hào)和花括號(hào)）內(nèi)換行，如： class Edit(CBase): def _init_(self, parent, width, font = FONT, color = BLACK, pos = POS, style = 0): 或： very_very_very_long_variable_name = Edit(parent, width, font, color, pos) 如果行長到連第一個(gè)括號(hào)內(nèi)的參數(shù)都放不下，則每個(gè)元素都單獨(dú)占一行： very_very_very_long_variable_name = ui.widgets.Edit( panrent, width, font, color, pos)3)在長行加入續(xù)行符強(qiáng)行斷行，斷行的位置應(yīng)在操作符前，且換行后多一個(gè)縮進(jìn)，以使維護(hù)人員看代碼的時(shí)候看到代碼行首即可判定這里存在換行，如：if color = WHITE or color = BLACK or color = BLUE: # 注意 or 操作符在新行的行首而不是舊行的行尾do_something(color);命名 一致的命名可以給開發(fā)人員減少許多麻煩，而恰如其分的命名則可以大幅提高代碼的可讀性，降低維護(hù)成本。常量常量名所有字母大寫，由下劃線連接各個(gè)單詞，如WHITE = 0XFFFFFFTHIS_IS_A_CONSTANT = 1變量 變量名全部小寫，由下劃線連接各個(gè)單詞，如color = WHITEthis_is_a_variable = 1 不論是類成員變量還是全局變量，均不使用 m 或 g 前綴。私有類成員使用單一下劃線前綴標(biāo)識(shí)，多定義公開成員，少定義私有成員。 變量名不應(yīng)帶有類型信息，因?yàn)?Python 是動(dòng)態(tài)類型語言。如 iValue、names_list、dict_obj 等都是不好的命名。函數(shù) 函數(shù)名的命名規(guī)則與變量名相同。類 類名單詞首字母大寫，不使用下劃線連接單詞，也不加入 C、T 等前綴。如：class ThisIsAClass(object): passs模塊 模塊名全部小寫，對(duì)于包內(nèi)使用的模塊，可以加一個(gè)下劃線前綴，如module.py_internal_module.py包 包的命名規(guī)范與模塊相同?？s寫 命名應(yīng)當(dāng)盡量使用全拼寫的單詞，縮寫的情況有如下兩種：1）常用的縮寫，如 XML、ID等，在命名時(shí)也應(yīng)只大寫首字母，如class XmlParser(object):pass2）命名中含有長單詞，對(duì)某個(gè)單詞進(jìn)行縮寫。這時(shí)應(yīng)使用約定成俗的縮寫方式，如去除元音、包含輔音的首字符等方式，例如：function 縮寫為 fntext 縮寫為 txtobject 縮寫為 objcount 縮寫為 cntnumber 縮寫為 num，等。特定命名方式 主要是指 _xxx_ 形式的系統(tǒng)保留字命名法。項(xiàng)目中也可以使用這種命名，它的意義在于這種形式的變量是只讀的，這種形式的類成員函數(shù)盡量不要重載。如 class Base(object): def _init_(self, id, parent = None): self._id_ = id self._parent_ = parent def _message_(self, msgid): # 略其中 _id_、_parent_ 和 _message_ 都采用了系統(tǒng)保留字命名法。語句import import 語句有以下幾個(gè)原則需要遵守：1）import 的次序，先 import Python 內(nèi)置模塊，再 import 第三方模塊，最后 import 自己開發(fā)的項(xiàng)目中的其它模塊；這幾種模塊中用空行分隔開來。2）一條 import 語句 import 一個(gè)模塊。3）當(dāng)從模塊中 import 多個(gè)對(duì)象且超過一行時(shí)，使用如下斷行法（此語法 py2.5 以上版本才支持）：from module import (obj1, obj2, obj3, obj4, obj5, obj6)4）不要使用 from module import *，除非是 import 常量定義模塊或其它你確保不會(huì)出現(xiàn)命名空間沖突的模塊。賦值 對(duì)于賦值語言，主要是不要做無謂的對(duì)齊，如：a= 1# 這是一個(gè)行注釋variable= 2# 另一個(gè)行注釋fn= callback_function# 還是行注釋沒有必要做這種對(duì)齊，原因有兩點(diǎn)：一是這種對(duì)齊會(huì)打亂編程時(shí)的注意力，大腦要同時(shí)處理兩件事（編程和對(duì)齊）；二是以后閱讀和維護(hù)都很困難，因?yàn)槿搜鄣臋M向視野很窄，把三個(gè)字段看成一行很困難，而且維護(hù)時(shí)要增加一個(gè)更長的變量名也會(huì)破壞對(duì)齊。直接這樣寫為佳：a = 1 # 這是一個(gè)行注釋variable = 2 # 另一個(gè)行注釋fn = callback_function # 還是行注釋分枝和循環(huán) 對(duì)于分枝和循環(huán)，有如下幾點(diǎn)需要注意的：1)不要寫成一行，如：if !flg: pass 和 for i in xrange(10): print i都不是好代碼，應(yīng)寫成if !flg: passfor i in xrange(10): print i注：本文檔中出現(xiàn)寫成一行的例子是因?yàn)榕虐娴脑?，不得作為編碼中不斷行的依據(jù)。2)條件表達(dá)式的編寫應(yīng)該足夠 pythonic，如以下形式的條件表達(dá)式是拙劣的：if len(alist) != 0: do_something()if alist != : do_something()if s != “”: do_something()if var != None: do_something()if var != False: do_something()上面的語句應(yīng)該寫成：if seq: do_somethin() # 注意，這里命名也更改了if var: do_something()3)用得著的時(shí)候多使用循環(huán)語句的 else 分句，以簡化代碼。已有代碼 對(duì)于項(xiàng)目中已有的代碼，可能因?yàn)闅v史遺留原因不符合本規(guī)范，應(yīng)當(dāng)看作可以容忍的特例，允許存在；但不應(yīng)在新的代碼中延續(xù)舊的風(fēng)格。 對(duì)于第三方模塊，可能不符合本規(guī)范，也應(yīng)看作可以容忍的特例，允許存在；但不應(yīng)在新的代碼中使用第三方模塊的風(fēng)格。 tab 與空格混用的縮進(jìn)是不可容