簡明 Python 編程規范

簡明 Python 編程規范
編碼
??? 所有的 Python 腳本文件都應在文件頭標上 # -*- coding:utf-8 -*- 。設置編輯器，默認保存為 utf-8 格式。
注釋
??? 業界普遍認同 Python 的注釋分為兩種的概念，一種是由 # 開頭的“真正的”注釋，另一種是 docstrings。前者表明為何選擇當前實現以及這種實現的原理和難點，后者表明如何使用這個包、模塊、類、函數（方法），甚至包括使用示例和單元測試。
??? 堅持適當注釋原則。對不存在技術難點的代碼堅持不注釋，對存在技術難點的代碼必須注釋。但與注釋不同，推薦對每一個包、模塊、類、函數（方法）寫 docstrings，除非代碼一目了然，非常簡單。
縮進
??? Python 依賴縮進來確定代碼塊的層次，行首空白符主要有兩種：tab 和空格，但嚴禁兩者混用。如果使用 tab 縮進，設定 tab 為 4 個空格。
??? 公司內部推薦使用 4 個空格的 tab 進行縮進。
空格
??? 空格在 Python 代碼中是有意義的，因為 Python 的語法依賴于縮進，在行首的空格稱為前導空格。在這一節不討論前導空格相關的內容，只討論非前導空格。非前導空格在 Python 代碼中沒有意義，但適當地加入非前導空格可以增進代碼的可讀性。
1）在二元算術、邏輯運算符前后加空格：如 a = b + c；
2）在一元前綴運算符后不加空格，如 if !flg: pass；
3） “:”用在行尾時前后皆不加空格，如分枝、循環、函數和類定義語言；用在非行尾時兩端加空格，如 dict 對象的定義 d = {‘key’ : ’value’}。
4）括號（含圓括號、方括號和花括號）前后不加空格，如 do_something(arg1, arg2)，而不是 do_something( arg1, arg2 )；
5）逗號后面加一個空格，前面不加空格；s
空行
??? 適當的空行有利于增加代碼的可讀性，加空行可以參考如下幾個準則：
1）在類、函數的定義間加空行；
2）在 import 不同種類的模塊間加工行；
3）在函數中的邏輯段落間加空行，即把相關的代碼緊湊寫在一起，作為一個邏輯段落，段落間以空行分隔；
斷行
??? 盡管現在的寬屏顯示器已經可以單屏顯示超過 256 列字符，但本規范仍然堅持行的最大長度不得超過 78 個字符的標準。折疊長行的方法有以下幾種方法：
1) 為長變量名換一個短名，如：
??? this.is.a.very.long.variable_name = this.is.another.long.variable_name
??? 應改為：
??? variable_name1 = this.is.a.very.long.variable_name
??? variable_name2 = this.is.another.variable_name
??? variable_name1 = variable_name2s
2) 在括號（包括圓括號、方括號和花括號）內換行，如：
??? 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)
??? 如果行長到連第一個括號內的參數都放不下，則每個元素都單獨占一行：
??? very_very_very_long_variable_name = ui.widgets.Edit( \
??????????????????????????????????????????????????????????????????????????????????? panrent, \
??????????????????????????????????????????????????????????????????????????????????? width, \
??????????????????????????????????????????????????????????????????????????????????? font, \
??????????????????????????????????????????????????????????????????????????????????? color, \
??????????????????????????????????????????????????????????????????????????????????? pos)
3) 在長行加入續行符強行斷行，斷行的位置應在操作符前，且換行后多一個縮進，以使維護人員看代碼的時候看到代碼行首即可判定這里存在換行，如：
if color == WHITE or color == BLACK \
or color == BLUE: # 注意 or 操作符在新行的行首而不是舊行的行尾
do_something(color);
命名
??? 一致的命名可以給開發人員減少許多麻煩，而恰如其分的命名則可以大幅提高代碼的可讀性，降低維護成本。
常量
?常量名所有字母大寫，由下劃線連接各個單詞，如
WHITE = 0XFFFFFF
THIS_IS_A_CONSTANT = 1
變量
??? 變量名全部小寫，由下劃線連接各個單詞，如
color = WHITE
this_is_a_variable = 1
??? 不論是類成員變量還是全局變量，均不使用 m 或 g 前綴。私有類成員使用單一下劃線前綴標識，多定義公開成員，少定義私有成員。
??? 變量名不應帶有類型信息，因為 Python 是動態類型語言。如 iValue、names_list、dict_obj 等都是不好的命名。
函數
??? 函數名的命名規則與變量名相同。
類
??? 類名單詞首字母大寫，不使用下劃線連接單詞，也不加入 C、T 等前綴。如：
class ThisIsAClass(object):
??? passs
模塊
??? 模塊名全部小寫，對于包內使用的模塊，可以加一個下劃線前綴，如
module.py
_internal_module.py
包
??? 包的命名規范與模塊相同。
縮寫
??? 命名應當盡量使用全拼寫的單詞，縮寫的情況有如下兩種：
1）常用的縮寫，如 XML、ID等，在命名時也應只大寫首字母，如
class XmlParser(object):pass
2）命名中含有長單詞，對某個單詞進行縮寫。這時應使用約定成俗的縮寫方式，如去除元音、包含輔音的首字符等方式，例如：
function 縮寫為 fn
text 縮寫為 txt
object 縮寫為 obj
count 縮寫為 cnt
number 縮寫為 num，等。
特定命名方式
??? 主要是指 __xxx__ 形式的系統保留字命名法。項目中也可以使用這種命名，它的意義在于這種形式的變量是只讀的，這種形式的類成員函數盡量不要重載。如
class Base(object):
??? def __init__(self, id, parent = None):
??????? self.__id__ = id
??????? self.__parent__ = parent
??? def __message__(self, msgid):
??????? # …略
其中 __id__、__parent__ 和 __message__ 都采用了系統保留字命名法。
語句
import
??? import 語句有以下幾個原則需要遵守：
1） import 的次序，先 import Python 內置模塊，再 import 第三方模塊，最后 import 自己開發的項目中的其它模塊；這幾種模塊中用空行分隔開來。
2）一條 import 語句 import 一個模塊。
3）當從模塊中 import 多個對象且超過一行時，使用如下斷行法（此語法 py2.5 以上版本才支持）：
from module import (obj1, obj2, obj3, obj4,
??????????????????????????????????? obj5, obj6)
4）不要使用 from module import *，除非是 import 常量定義模塊或其它你確保不會出現命名空間沖突的模塊。
賦值
??? 對于賦值語言，主要是不要做無謂的對齊，如：
a?? = 1???? # 這是一個行注釋
variable? = 2???? # 另一個行注釋
fn?? = callback_function? # 還是行注釋
沒有必要做這種對齊，原因有兩點：一是這種對齊會打亂編程時的注意力，大腦要同時處理兩件事（編程和對齊）；二是以后閱讀和維護都很困難，因為人眼的橫向視野很窄，把三個字段看成一行很困難，而且維護時要增加一個更長的變量名也會破壞對齊。直接這樣寫為佳：
a = 1 # 這是一個行注釋
variable = 2 # 另一個行注釋
fn = callback_function # 還是行注釋
分枝和循環
??? 對于分枝和循環，有如下幾點需要注意的：
1) 不要寫成一行，如：
if !flg: pass 和 for i in xrange(10): print i都不是好代碼，應寫成
if !flg:
??? pass
for i in xrange(10):
??? print i
注：本文檔中出現寫成一行的例子是因為排版的原因，不得作為編碼中不斷行的依據。
2) 條件表達式的編寫應該足夠 pythonic，如以下形式的條件表達式是拙劣的：
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 seq: do_somethin() # 注意，這里命名也更改了
if var: do_something()
3) 用得著的時候多使用循環語句的 else 分句，以簡化代碼。
已有代碼
??? 對于項目中已有的代碼，可能因為歷史遺留原因不符合本規范，應當看作可以容忍的特例，允許存在；但不應在新的代碼中延續舊的風格。
??? 對于第三方模塊，可能不符合本規范，也應看作可以容忍的特例，允許存在；但不應在新的代碼中使用第三方模塊的風格。
??? tab 與空格混用的縮進是不可容忍的，在運行項目時應使用 –t 或 –tt 選項排查這種可能性存在。出現混用的情況時，如果是公司開發的基礎類庫代碼，應當通知類庫維護人員修改；第三方模塊則可以通過提交 patch 等方式敦促開發者修正問題。
已有風格
??? 開發人員往往在加入項目之前已經形成自有的編碼風格，加入項目后應以本規范為準編寫代碼。特別是匈牙利命名法，因為帶有類型信息，并不適合 Python 編程，不應在 Python 項目中應用。