簡明 Python 編程規範v2 .

賴勇浩（http://laiyonghao.com）

註：之前發布一篇《簡明 Python 編程規範》（見：http://blog.csdn.net/lanphaday/article/details/2834883），本是我給當時所在的公司制定的，發表到部落格的時候，對齊等問題都有一些錯誤，還包括一些錯別字。到後來，我又有做過修正。大概在 2010 年 8 年，我又由 C++ 開發轉到 Python 開發，便在那之前的基礎上潤飾和完善，形成第二版。前段時間 simple-is-better.com 網站轉寄了我寫的前一版本規範（見：http://simple-is-better.com/news/534），引起大家的討論，我一一解釋不來，所以今天抽點時間把 v2 編輯一下發布上來，求交流、指正。

以下是為規範全文：

Python編程規範v2執行

•  本規範使用 pylint 及對應的設定檔來進行檢測，關於 pylint 的安裝和配置見：http://blog.csdn.net/lanphaday/article/details/6089902

編碼

• 所有的 Python 指令檔都應在檔案頭標上如下標識或其相容格式的標識：

 

# -*- coding:utf-8 -*-

設定編輯器，預設儲存為 utf-8 格式。
注釋

• 業界普遍認同 Python 的注釋分為兩種的概念，一種是由 # 開頭的“真正的”注釋，另一種是 docstrings。前者表明為何選擇當前實現以及這種實現的原理和痛點，後者表明如何使用這個包、模組、類、函數（方法），甚至包括使用樣本和單元測試。
• 堅持適當注釋原則。對不存在技術痛點的代碼堅持不注釋，對存在技術痛點的代碼必須注釋。但與注釋不同，推薦對每一個包、模組、類、函數（方法）寫 docstrings，除非代碼一目瞭然，非常簡單。

格式縮排

• Python 依賴縮排來確定代碼塊的層次，行首空白符主要有兩種：tab 和空格，但嚴禁兩者混用。
• 公司內部使用 2 個空格的 tab 進行縮排。

空格

•  空格在 Python 代碼中是有意義的，因為 Python 的文法依賴於縮排，在行首的空格稱為前置空格。在這一節不討論前置空格相關的內容，只討論非前置空格。非前置空格在 Python 代碼中沒有意義，但適當地加入非前置空格可以增進代碼的可讀性。
• 在二元算術、邏輯運算子前後加空格，如：

• a = b + c

 

“:”用在行尾時前後皆不加空格，如分枝、迴圈、函數和類定義語言；用在非行尾時兩端加空格，如 dict 對象的定義：view plaincopy to clipboardprint?

1. d = {'key' : 'value'}  

d = {'key' : 'value'}

括弧（含圓括弧、方括弧和花括弧）前後不加空格，如：view plaincopy to clipboardprint?

1. do_something(arg1, arg2)  

do_something(arg1, arg2)

而不是view plaincopy to clipboardprint?

1. do_something( arg1, arg2 )  

do_something( arg1, arg2 )

逗號後面加一個空格，前面不加空格；

空行

• 適當的空行有利於增加代碼的可讀性，加空行可以參考如下幾個準則：

• 在類、函數的定義間加空行；
• 在 import 不同種類的模組間加工行；
• 在函數中的邏輯段落間加空行，即把相關的代碼緊湊寫在一起，作為一個邏輯段落，段落間以空行分隔；

斷行

• 儘管現在的寬屏顯示器已經可以單屏顯示超過 256 列字元，但本規範仍然堅持行的最大長度不得超過 78 個字元的標準。摺疊長行的方法有以下幾種方法：

• 為長變數名換一個短名，如：

view plaincopy to clipboardprint?

1. this._is.a.very.long.variable_name = this._is.another.long.variable_name  

this._is.a.very.long.variable_name = this._is.another.long.variable_name

應改為：view plaincopy to clipboardprint?

1. variable_name1 = this._is.a.very.long.variable_name variable_name2 = this._is.another.variable_name variable_name1 = variable_name2s  

variable_name1 = this._is.a.very.long.variable_name variable_name2 = this._is.another.variable_name variable_name1 = variable_name2s

• 在括弧（包括圓括弧、方括弧和花括弧）內換行，如：

view plaincopy to clipboardprint?

1. class Edit(Widget): def __init__(self, parent, width, font = FONT, color = BLACK, pos = POS, style = 0): # 注意：多一層縮排 pass  

class Edit(Widget): def __init__(self, parent, width, font = FONT, color = BLACK, pos = POS, style = 0): # 注意：多一層縮排 pass

或：

view plaincopy to clipboardprint?

1. very_very_very_long_variable_name = Edit(parent, width, font, color, pos) # 注意：多一層縮排 do_sth_with(very_very_very_long_variable_name)  

very_very_very_long_variable_name = Edit(parent, width, font, color, pos) # 注意：多一層縮排 do_sth_with(very_very_very_long_variable_name)

• 如果行長到連第一個括弧內的參數都放不下，則每個元素都單獨佔一行：

view plaincopy to clipboardprint?

1. very_very_very_long_variable_name = ui.widgets.Edit( panrent, width, font, color, pos) # 注意：多一層縮排 do_sth_with(very_very_very_long_variable_name)  

very_very_very_long_variable_name = ui.widgets.Edit( panrent, width, font, color, pos) # 注意：多一層縮排 do_sth_with(very_very_very_long_variable_name)

• 在長行加入續行符強行斷行，斷行的位置應在操作符前，且換行後多一個縮排，以使維護人員看代碼的時候看到程式碼首即可判定這裡存在換行，如：

view plaincopy to clipboardprint?

1. if color == WHITE or color == BLACK \ or color == BLUE: # 注意 or 操作符在新行的行首而不是舊行的行尾，上一行的續行符不可省略 do_something(color); else: do_something(DEFAULT_COLOR);  

if color == WHITE or color == BLACK \ or color == BLUE: # 注意 or 操作符在新行的行首而不是舊行的行尾，上一行的續行符不可省略 do_something(color); else: do_something(DEFAULT_COLOR);

命名

• 一致的命名可以給開發人員減少許多麻煩，而恰如其分的命名則可以大幅提高代碼的可讀性，降低維護成本。

常量

• 常量名所有字母大寫，由底線串連各個單詞，如：

view plaincopy to clipboardprint?

1. WHITE = 0xffffffff THIS_IS_A_CONSTANT = 1  

WHITE = 0xffffffff THIS_IS_A_CONSTANT = 1

變數

• 變數名全部小寫，由底線串連各個單詞，如：

view plaincopy to clipboardprint?

1. color = WHITE this_is_a_variable = 1  

color = WHITE this_is_a_variable = 1

• 不論是類成員變數還是全域變數，均不使用 m 或 g 首碼。私人類成員使用單一底線首碼標識，多定義公開成員，少定義私人成員。

• 變數名不應帶有類型資訊，因為 Python 是動態類型語言。如 iValue、names_list、dict_obj 等都是不好的命名。

函數

• 函數名的命名規則與變數名相同。

類

• 類名單字首大寫，不使用底線串連單詞，也不加入 C、T 等首碼。如：

view plaincopy to clipboardprint?

1. class ThisIsAClass(object): passs  

class ThisIsAClass(object): passs

模組

• 模組名全部小寫，對於包內使用的模組，可以加一個底線首碼，如：

view plaincopy to clipboardprint?

1. module.py _internal_module.py  

module.py _internal_module.py

包

• 包的命名規範與模組相同。

縮寫

• 命名應當盡量使用全拼字的單詞，縮寫的情況有如下兩種：

• 常用的縮寫，如 XML、ID等，在命名時也應只大寫首字母，如：

view plaincopy to clipboardprint?

1. class XmlParser(object):pass  

class XmlParser(object):pass

• 命名中含有長單詞，對某個單詞進行縮寫。這時應使用約定成俗的縮寫方式，如去除母音、包含輔音的首字元等方式，例如：

• function 縮寫為 fn
• text 縮寫為 txt
• object 縮寫為 obj
• count 縮寫為 cnt
• number 縮寫為 num，等。

特定命名方式

• 主要是指 __xxx__ 形式的系統保留字命名法。項目中也可以使用這種命名，它的意義在於這種形式的變數是唯讀，這種形式的類成員函數盡量不要重載。如：

view plaincopy to clipboardprint?

1. class Base(object): def __init__(self, id, parent = None): self.__id__ = id self.__parent__ = parent def __message__(self, msgid): # …略  

class Base(object): def __init__(self, id, parent = None): self.__id__ = id self.__parent__ = parent def __message__(self, msgid): # …略

其中 __id__、__parent__ 和 __message__ 都採用了系統保留字命名法。

語句import

• import 語句有以下幾個原則需要遵守：

• import 的次序，先 import Python 內建模組，再 import 第三方模組，最後 import 自己開發的項目中的其它模組；這幾種模組中用空行分隔開來。
• 一條 import 語句 import 一個模組。
• 當從模組中 import 多個對象且超過一行時，使用如下斷行法（此文法 py2.5 以上版本才支援）：

view plaincopy to clipboardprint?

1. from module import (obj1, obj2, obj3, obj4, obj5, obj6)  

from module import (obj1, obj2, obj3, obj4, obj5, obj6)

• 不要使用 from module import *，除非是 import 常量定義模組或其它你確保不會出現命名空間衝突的模組。

賦值

• 對於指派陳述式，主要是不要做無謂的對齊，如：

view plaincopy to clipboardprint?

1. a = 1 # 這是一個行注釋 variable = 2 # 另一個行注釋 fn = callback_function # 還是行注釋  

a = 1 # 這是一個行注釋 variable = 2 # 另一個行注釋 fn = callback_function # 還是行注釋

沒有必要做這種對齊，原因有兩點：一是這種對齊會打亂編程時的注意力，大腦要同時處理兩件事（編程和對齊）；二是以後閱讀和維護都很困難，因為人眼的橫向視野很窄，把三個欄位看成一行很困難，而且維護時要增加一個更長的變數名也會破壞對齊。直接這樣寫為佳：

view plaincopy to clipboardprint?

1. a = 1 # 這是一個行注釋 variable = 2 # 另一個行注釋 fn = callback_function # 還是行注釋  

a = 1 # 這是一個行注釋 variable = 2 # 另一個行注釋 fn = callback_function # 還是行注釋

分枝和迴圈

• 對於分枝和迴圈，有如下幾點需要注意的：

• 不要寫成一行，如：

view plaincopy to clipboardprint?

1. if not flg: pass  

if not flg: pass

和

view plaincopy to clipboardprint?

1. for i in xrange(10): print i  

for i in xrange(10): print i

都不是好代碼，應寫成

view plaincopy to clipboardprint?

1. if not flg: pass for i in xrange(10): print i  

if not flg: pass for i in xrange(10): print i

註：本文檔中出現寫成一行的例子是因為排版的原因，不得作為編碼中不斷行的依據。

• 條件運算式的編寫應該足夠 pythonic，如以下形式的條件運算式是拙劣的：

view plaincopy to clipboardprint?

1. if len(alist) != 0: do_something() if alist != []: do_something() if s != "": do_something() if var != None: do_something() if var != False: do_something()  

if len(alist) != 0: do_something() if alist != []: do_something() if s != "": do_something() if var != None: do_something() if var != False: do_something()

上面的語句應該寫成：

view plaincopy to clipboardprint?

1. if seq: do_somethin() # 注意，這裡命名也更改了 if var: do_something()  

if seq: do_somethin() # 注意，這裡命名也更改了 if var: do_something()

• 用得著的時候多使用迴圈語句的 else 分句，以簡化代碼。

已有代碼

• 對於項目中已有的代碼，可能因為曆史遺留原因不符合本規範，應當看作可以容忍的特例，允許存在；但不應在新的代碼中延續舊的風格。
• 對於第三方模組，可能不符合本規範，也應看作可以容忍的特例，允許存在；但不應在新的代碼中使用第三方模組的風格。
• tab 與空格混用的縮排是'''不可容忍'''的，在運行項目時應使用 -t 或 -tt 選項排查這種可能性存在。出現混用的情況時，如果是公司開發的基礎類庫代碼，應當通知類庫維護人員修改；第三方模組則可以通過提交 patch 等方式敦促開發人員修正問題。

已有風格

• 開發人員往往在加入項目之前已經形成自有的編碼風格，加入項目後應以本規範為準編寫代碼。特別是匈牙利命名法，因為帶有類型資訊，並不適合 Python 編程，不應在 Python 項目中應用。

 

 轉自：http://blog.csdn.net/lanphaday/article/details/6601123