簡明 Python 編程規範

更新：2011 年 7 月 12 日發布了新版本的規範，見：http://blog.csdn.net/lanphaday/article/details/6601123，關於舊版本的所有問題不再回覆，還請見諒。

本文最初發表於賴勇浩（戀花蝶）的部落格：http://blog.csdn.net/lanphaday，如蒙轉載，必須保留全文完整，未經本人同意，不得用於商業目的。
簡明 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 項目中應用。