|
本文最初發(fā)表于賴勇浩（戀花蝶）的博客：http://blog.csdn.net/lanphaday，如蒙轉(zhuǎn)載，必須保留全文完整，未經(jīng)本人同意，不得用于商業(yè)目的。 簡(jiǎn)明 Python 編程規(guī)范 編碼 所有的 Python 腳本文件都應(yīng)在文件頭標(biāo)上 # -*- coding:utf-8 -*- 。設(shè)置編輯器，默認(rèn)保存為 utf-8 格式。 注釋 業(yè)界普遍認(rèn)同 Python 的注釋分為兩種的概念，一種是由 # 開(kāi)頭的“真正的”注釋，另一種是 docstrings。前者表明為何選擇當(dāng)前實(shí)現(xiàn)以及這種實(shí)現(xiàn)的原理和難點(diǎn)，后者表明如何使用這個(gè)包、模塊、類、函數(shù)（方法），甚至包括使用示例和單元測(cè)試。 堅(jiān)持適當(dāng)注釋原則。對(duì)不存在技術(shù)難點(diǎn)的代碼堅(jiān)持不注釋，對(duì)存在技術(shù)難點(diǎn)的代碼必須注釋。但與注釋不同，推薦對(duì)每一個(gè)包、模塊、類、函數(shù)（方法）寫(xiě) docstrings，除非代碼一目了然，非常簡(jiǎn)單。 縮進(jìn) Python 依賴縮進(jìn)來(lái)確定代碼塊的層次，行首空白符主要有兩種：tab 和空格，但嚴(yán)禁兩者混用。如果使用 tab 縮進(jìn)，設(shè)定 tab 為 4 個(gè)空格。 公司內(nèi)部推薦使用 4 個(gè)空格的 tab 進(jìn)行縮進(jìn)。 空格 空格在 Python 代碼中是有意義的，因?yàn)?Python 的語(yǔ)法依賴于縮進(jìn)，在行首的空格稱為前導(dǎo)空格。在這一節(jié)不討論前導(dǎo)空格相關(guān)的內(nèi)容，只討論非前導(dǎo)空格。非前導(dǎo)空格在 Python 代碼中沒(méi)有意義，但適當(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ù)和類定義語(yǔ)言；用在非行尾時(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)的代碼緊湊寫(xiě)在一起，作為一個(gè)邏輯段落，段落間以空行分隔； 斷行 盡管現(xiàn)在的寬屏顯示器已經(jīng)可以單屏顯示超過(guò) 256 列字符，但本規(guī)范仍然堅(jiān)持行的最大長(zhǎng)度不得超過(guò) 78 個(gè)字符的標(biāo)準(zhǔn)。折疊長(zhǎng)行的方法有以下幾種方法： 1) 為長(zhǎng)變量名換一個(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_name2s 2) 在括號(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) 如果行長(zhǎng)到連第一個(gè)括號(hào)內(nèi)的參數(shù)都放不下，則每個(gè)元素都單獨(dú)占一行： very_very_very_long_variable_name = ui.widgets.Edit( \ panrent, \ width, \ font, \ color, \ pos) 3) 在長(zhǎng)行加入續(xù)行符強(qiáng)行斷行，斷行的位置應(yīng)在操作符前，且換行后多一個(gè)縮進(jìn)，以使維護(hù)人員看代碼的時(shí)候看到代碼行首即可判定這里存在換行，如： if color == WHITE or color == BLACK \ or color == BLUE: # 注意 or 操作符在新行的行首而不是舊行的行尾 do_something(color); 命名 一致的命名可以給開(kāi)發(fā)人員減少許多麻煩，而恰如其分的命名則可以大幅提高代碼的可讀性，降低維護(hù)成本。 常量 常量名所有字母大寫(xiě)，由下劃線連接各個(gè)單詞，如 WHITE = 0XFFFFFF THIS_IS_A_CONSTANT = 1 變量 變量名全部小寫(xiě)，由下劃線連接各個(gè)單詞，如 color = WHITE this_is_a_variable = 1 不論是類成員變量還是全局變量，均不使用 m 或 g 前綴。私有類成員使用單一下劃線前綴標(biāo)識(shí)，多定義公開(kāi)成員，少定義私有成員。 變量名不應(yīng)帶有類型信息，因?yàn)?Python 是動(dòng)態(tài)類型語(yǔ)言。如 iValue、names_list、dict_obj 等都是不好的命名。 函數(shù) 函數(shù)名的命名規(guī)則與變量名相同。 類 類名單詞首字母大寫(xiě)，不使用下劃線連接單詞，也不加入 C、T 等前綴。如： class ThisIsAClass(object): passs 模塊 模塊名全部小寫(xiě)，對(duì)于包內(nèi)使用的模塊，可以加一個(gè)下劃線前綴，如 module.py _internal_module.py 包 包的命名規(guī)范與模塊相同。 縮寫(xiě) 命名應(yīng)當(dāng)盡量使用全拼寫(xiě)的單詞，縮寫(xiě)的情況有如下兩種： 1） 常用的縮寫(xiě)，如 XML、ID等，在命名時(shí)也應(yīng)只大寫(xiě)首字母，如 class XmlParser(object):pass 2） 命名中含有長(zhǎng)單詞，對(duì)某個(gè)單詞進(jìn)行縮寫(xiě)。這時(shí)應(yīng)使用約定成俗的縮寫(xiě)方式，如去除元音、包含輔音的首字符等方式，例如： function 縮寫(xiě)為 fn text 縮寫(xiě)為 txt object 縮寫(xiě)為 obj count 縮寫(xiě)為 cnt number 縮寫(xiě)為 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)保留字命名法。 語(yǔ)句 import import 語(yǔ)句有以下幾個(gè)原則需要遵守： 1） import 的次序，先 import Python 內(nèi)置模塊，再 import 第三方模塊，最后 import 自己開(kāi)發(fā)的項(xiàng)目中的其它模塊；這幾種模塊中用空行分隔開(kāi)來(lái)。 2） 一條 import 語(yǔ)句 import 一個(gè)模塊。 3） 當(dāng)從模塊中 import 多個(gè)對(duì)象且超過(guò)一行時(shí)，使用如下斷行法（此語(yǔ)法 py2.5 以上版本才支持）： from module import (obj1, obj2, obj3, obj4, obj5, obj6) 4） 不要使用 from module import *，除非是 import 常量定義模塊或其它你確保不會(huì)出現(xiàn)命名空間沖突的模塊。 賦值 對(duì)于賦值語(yǔ)言，主要是不要做無(wú)謂的對(duì)齊，如： a = 1 # 這是一個(gè)行注釋 variable = 2 # 另一個(gè)行注釋 fn = callback_function # 還是行注釋 沒(méi)有必要做這種對(duì)齊，原因有兩點(diǎn)：一是這種對(duì)齊會(huì)打亂編程時(shí)的注意力，大腦要同時(shí)處理兩件事（編程和對(duì)齊）；二是以后閱讀和維護(hù)都很困難，因?yàn)槿搜鄣臋M向視野很窄，把三個(gè)字段看成一行很困難，而且維護(hù)時(shí)要增加一個(gè)更長(zhǎng)的變量名也會(huì)破壞對(duì)齊。直接這樣寫(xiě)為佳： a = 1 # 這是一個(gè)行注釋 variable = 2 # 另一個(gè)行注釋 fn = callback_function # 還是行注釋 分枝和循環(huán) 對(duì)于分枝和循環(huán)，有如下幾點(diǎn)需要注意的： 1) 不要寫(xiě)成一行，如： if !flg: pass 和 for i in xrange(10): print i都不是好代碼，應(yīng)寫(xiě)成 if !flg: pass for i in xrange(10): print i 注：本文檔中出現(xiàn)寫(xiě)成一行的例子是因?yàn)榕虐娴脑?，不得作為編碼中不斷行的依據(jù)。 2) 條件表達(dá)式的編寫(xiě)應(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ǔ)句應(yīng)該寫(xiě)成： if seq: do_somethin() # 注意，這里命名也更改了 if var: do_something() 3) 用得著的時(shí)候多使用循環(huán)語(yǔ)句的 else 分句，以簡(jiǎn)化代碼。 已有代碼 對(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)是不可容忍的，在運(yùn)行項(xiàng)目時(shí)應(yīng)使用 –t 或 –tt 選項(xiàng)排查這種可能性存在。出現(xiàn)混用的情況時(shí)，如果是公司開(kāi)發(fā)的基礎(chǔ)類庫(kù)代碼，應(yīng)當(dāng)通知類庫(kù)維護(hù)人員修改；第三方模塊則可以通過(guò)提交 patch 等方式敦促開(kāi)發(fā)者修正問(wèn)題。 已有風(fēng)格 開(kāi)發(fā)人員往往在加入項(xiàng)目之前已經(jīng)形成自有的編碼風(fēng)格，加入項(xiàng)目后應(yīng)以本規(guī)范為準(zhǔn)編寫(xiě)代碼。特別是匈牙利命名法，因?yàn)閹в蓄愋托畔?，并不適合 Python 編程，不應(yīng)在 Python 項(xiàng)目中應(yīng)用。 |
|
|
來(lái)自： Dawnxu > 《我的圖書(shū)館》
