【轉】python代碼風格-PEP8

轉載自http://www.douban.com/note/134971609/

Python 的代碼風格由 PEP 8 描述。這個文檔描述了 Python 編程風格的方方面面。在遵照這個文檔的條件下，不一樣程序員編寫的 Python 代碼能夠保持最大程度的類似風格。這樣就易於閱讀，易於在程序員之間交流。

1. 命名風格

1. 整體原則，新編代碼必須按下面命名風格進行，現有庫的編碼儘可能保持風格。
2. 儘可能以避免單獨使用小寫字母'l'，大寫字母'O'，以及大寫字母'I'等容易混淆的字母。
3. 模塊命名儘可能短小，使用所有小寫的方式，可使用下劃線。
4. 包命名儘可能短小，使用所有小寫的方式，不可使用下劃線。
5. 類的命名使用CapWords的方式，模塊內部使用的類採用_CapWords的方式。
6. 異常命名使用CapWords+Error後綴的方式。
7. 全局變量儘可能只在模塊內有效，相似C語言中的static。實現方法有兩種，一是__all__機制;二是前綴一個下劃線。對於不會發生改變的全局變量，使用大寫加下劃線。
8. 函數命名使用所有小寫的方式，可使用下劃線。
9. 常量命名使用所有大寫的方式，可使用下劃線。
10. 使用 has 或 is 前綴命名布爾元素，如: is_connect = True; has_member = False
11. 用複數形式命名序列。如：members = ['user_1', 'user_2']
12. 用顯式名稱命名字典，如：person_address = {'user_1':'10 road WD', 'user_2' : '20 street huafu'}
13. 避免通用名稱。諸如 list, dict, sequence 或者 element 這樣的名稱應該避免。又如os, sys 這種系統已經存在的名稱應該避免。
14. 類的屬性（方法和變量）命名使用所有小寫的方式，可使用下劃線。
15. 對於基類而言，可使用一個 Base 或者 Abstract 前綴。如BaseCookie、AbstractGroup
16. 內部使用的類、方法或變量前，需加前綴'_'代表此爲內部使用的。雖然如此，但這只是程序員之間的約定而非語法規定，用於警告說明這是一個私有變量，外部類不要去訪問它。但實際上，外部類仍是能夠訪問到這個變量。import不會導入如下劃線開頭的對象。
17. 類的屬性若與關鍵字名字衝突，後綴一下劃線，儘可能不要使用縮略等其餘方式。
18. 雙前導下劃線用於命名class屬性時，會觸發名字重整；雙前導和後置下劃線存在於用戶控制的名字空間的"magic"對象或屬性。
19. 爲避免與子類屬性命名衝突，在類的一些屬性前，前綴兩條下劃線。好比：類Foo中聲明__a,訪問時，只能經過Foo._Foo__a，避免歧義。若是子類也叫Foo，那就無能爲力了。
20. 類的方法第一個參數必須是self，而靜態方法第一個參數必須是cls。
21. 通常的方法、函數、變量需注意，如非必要，不要連用兩個前導和後置的下線線。兩個前導下劃線會致使變量在解釋期間被改名。兩個前導下劃線會致使函數被理解爲特殊函數，好比操做符重載等。

2 關於參數

1. 要用斷言來實現靜態類型檢測。斷言能夠用於檢查參數，但不該僅僅是進行靜態類型檢測。 Python 是動態類型語言，靜態類型檢測違背了其設計思想。斷言應該用於避免函數不被毫無心義的調用。
2. 不要濫用 *args 和 **kwargs。*args 和 **kwargs 參數可能會破壞函數的健壯性。它們使簽名變得模糊，並且代碼經常開始在不該該的地方構建小的參數解析器

3 代碼編排

1. 縮進。優先使用4個空格的縮進（編輯器均可以完成此功能），其次可以使用Tap，但堅定不能混合使用Tap和空格。
2. 每行最大長度79，換行可使用反斜槓，最好使用圓括號。換行點要在操做符的後邊敲回車。
3. 類和top-level函數定義之間空兩行；類中的方法定義之間空一行；函數內邏輯無關段落之間空一行；其餘地方儘可能不要再空行。
4. 一個函數 : 不要超過 30 行代碼, 便可顯示在一個屏幕類，能夠不使用垂直遊標便可看到整個函數；一個類 : 不要超過 200 行代碼，不要有超過 10 個方法；一個模塊 不要超過 500 行。

4. 文檔編排

1. 模塊內容的順序：模塊說明和docstring—import—globals&constants—其餘定義。其中import部分，又按標準、三方和本身編寫順序依次排放，之間空一行。
2. 不要在一句import中多個庫，好比import os, sys不推薦。
3. 若是採用from XX import XX引用庫，能夠省略‘module.’。如果可能出現命名衝突，這時就要採用import XX。

5. 空格的使用

1. 整體原則，避免沒必要要的空格。
2. 各類右括號前不要加空格。
3. 函數的左括號前不要加空格。如Func(1)。
4. 序列的左括號前不要加空格。如list[2]。
5. 逗號、冒號、分號前不要加空格。
6. 操做符（=/+=/-+/==/</>/!=/<>/<=/>=/in/not in/is/is not/and/or/not)左右各加一個空格，不要爲了對齊增長空格。若是操做符有優先級的區別，可考慮在低優先級的操做符兩邊添加空格。如：hypot2 = x*x + y*y;  c = (a+b) * (a-b)
7. 函數默認參數使用的賦值符左右省略空格。
8. 不要將多句語句寫在同一行，儘管使用‘；’容許。
9. if/for/while語句中，即便執行語句只有一句，也必須另起一行。

6. 註釋

1. 整體原則，錯誤的註釋不如沒有註釋。因此當一段代碼發生變化時，第一件事就是要修改註釋！避免無謂的註釋
2. 註釋必須使用英文，最好是完整的句子，首字母大寫，句後要有結束符，結束符後跟兩個空格，開始下一句。若是是短語，能夠省略結束符。
3. 行註釋：在一句代碼後加註釋，可是這種方式儘可能少使用。。好比：x = x + 1 # Increment
4. 塊註釋：在一段代碼前增長的註釋。在‘#’後加一空格。段落之間以只有‘#’的行間隔。好比：

# Description : Module config.
#
# Input : None
#
# Output : None

 7. 文檔描述

1. 爲全部的共有模塊、函數、類、方法寫docstrings；非共有的沒有必要，可是能夠寫註釋（在def的下一行）。
2. 若是docstring要換行，參考以下例子,詳見PEP 257

"""Return a foobang

Optional plotz says to frobnicate the bizbaz first.

"""

8. 編碼建議

1. 編碼中考慮到其餘python實現的效率等問題，好比運算符‘+’在CPython（Python）中效率很高，都是Jython中卻很是低，因此應該採用.join()的方式。
2. 與None之類的單件比較，儘量使用‘is’‘is not’，絕對不要使用‘==’，好比if x is not None 要優於if x。
3. 使用startswith() and endswith()代替切片進行序列前綴或後綴的檢查。好比：建議使用if foo.startswith('bar'): 而非if foo[:3] == 'bar':
4. 使用isinstance()比較對象的類型。好比：建議使用if isinstance(obj, int): 而非if type(obj) is type(1):
5. 判斷序列空或不空，有以下規則：建議使用if [not] seq: 而非if [not] len(seq)
6. 字符串不要以空格收尾。
7. 二進制數據判斷使用 if boolvalue的方式。
8. 使用基於類的異常，每一個模塊或包都有本身的異常類，此異常類繼承自Exception。錯誤型的異常類應添加"Error"後綴，非錯誤型的異常類無需添加。
9. 異常中不要使用裸露的except，except後跟具體的exceptions。
10. 異常中try的代碼儘量少。好比：

try:
value = collection[key]
except KeyError:
return key_not_found(key)
else:
return handle_value(value)

要優於

try:
# Too broad!
return handle_value(collection[key])
except KeyError:
# Will also catch KeyError raised by handle_value()
return key_not_found(key)

9. 驗證腳本

能夠安裝一個 pep8 腳本用於驗證你的代碼風格是否符合 PEP8。Ubuntu上的安裝能夠用命令：sudo apt-get install pep8