997
gooseeker集搜客
Python編程規範
1，Python編程規範
> 編碼
所有的 Python 腳本文件都應在文件頭標上
# -*- coding:utf-8 -*-
用於設置編輯器，默認保存為 utf-8 格式。
> 注釋
業界普遍認同 Python 的注釋分為兩種，
- 一種是由 # 開頭的“真正的”注釋，例如，用於表明為何選擇當前實現以及這種實現的原理和難點
- 另一種是 docstrings，例如，用於表明如何使用這個包、模塊、類、函數（方法），甚至包括使用示例和單元測試
堅持適當注釋原則。對不存在技術難點的代碼堅持不注釋，對存在技術難點的代碼必須注釋。但與注釋不同，建議對每一個包、模塊、類、函數（方法）寫 docstrings，除非代碼一目了然，非常簡單。
> 縮進
Python 依賴縮進來確定代碼塊的層次，行首空白符主要有兩種：tab 和 空格，但嚴禁兩者混用。如果使用 tab 縮進，設定tab 為 4 個空格。
> 空格
空格在 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） 不要在逗號、分號、冒號前麵加空格，但應該在它們後麵加（除了在行尾）
6） 不要用空格來垂直對齊多行間的標記，因為這會成為維護的負擔（適用於:，#，=等）
> 空行
適當的空行有利於增加代碼的可讀性，加空行可以參考如下幾個準則：
- 在類、函數的定義間加空行；
- 在 import 不同種類的模塊間加空行；
- 在函數中的邏輯段落間加空行，即把相關的代碼緊湊寫在一起，作為一個邏輯段落，段落間以空行分隔；
> 斷行
盡管現在的寬屏顯示器已經可以單屏顯示超過 256 列字符，但本規範仍然堅持行的最大長度不得超過 80 個字符的標準。折疊長行的方法有以下幾種方法：
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) Python會將圓括號、中括號和花括號中的行隱式的連接起來，你可以利用這個特點。如需要，你可以在表達式外圍增加一對額外的圓括號
3) 在長行加入續行符強行斷行，斷行的位置應在操作符前，且換行後多一個縮進，以使維護人員看代碼的時候看到代碼行首即可判定這裏存在換行，如：
if color == WHITE or color == BLACK \
or color == BLUE: # 注意 or 操作符在新行的行首而不是舊行的行尾
do_something(color);
> 字符串
- 避免在循環中用+和+=操作符來累加字符串。由於字符串是不可變的，這樣做會創建不必要的臨時對象，並且導致二次方而不是線性的運行時間。作為替代方案，你可以將每個子串加入列表，然後在循環結束後用 .join 連接列表。（也可以將每個子串寫入一個 cStringIO.StringIO 緩存中）
- 為多行字符串使用三重雙引號而非三重單引號。不過要注意, 通常用隱式行連接更清晰，因為多行字符串與程序其他部分的縮進方式不一致。
命名
一致的命名可以給開發人員減少許多麻煩，而恰如其分的命名則可以大幅提高代碼的可讀性，降低維護成本。
>> 常量
常量名所有字母大寫，由下劃線連接各個單詞，如
WHITE = 0XFFFFFF
THIS_IS_A_CONSTANT = 1
>> 變量
變量名全部小寫，由下劃線連接各個單詞，如
color = WHITE
this_is_a_variable = 1
私有類成員使用單一下劃線前綴標識，多定義公開成員，少定義私有成員。
變量名不應帶有類型信息，因為 Python 是動態類型語言。如 iValue、names_list、dict_obj 等都是不好的命名。
>> 函數
函數名的命名規則與變量名相同。
>> 類
對類名使用大寫字母開頭的單詞（如CapWords, 即Pascal風格），不使用下劃線連接單詞。如：
class ThisIsAClass(object):pass
>> 模塊
模塊名全部小寫，對於包內使用的模塊，可以加一個下劃線前綴，如：
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 Python 內置模塊，再 import 第三方模塊，最後 import 自己開發的項目中的其它模塊；這幾種模塊用空行分隔開來。
- 每個import應該獨占一行。
- 不要使用 from module import *，除非是 import 常量定義模塊或其它你確保不會出現命名空間衝突的模塊。
> 賦值
對於賦值語言，主要是不要做無謂的對齊，如：
a = 1 # 這是一個行注釋
variable = 2 # 另一個行注釋
fn = callback_function # 還是行注釋
沒有必要做這種對齊，原因有兩點：一是這種對齊會打亂編程時的注意力，大腦要同時處理兩件事（編程和對齊）；二是以後閱讀和維護都很困難，因為人眼的橫向視野很窄，把三個字段看成一行很困難，而且維護時要增加一個更長的變量名也會破壞對齊。直接這樣寫為佳：
a = 1 # 這是一個行注釋
variable = 2 # 另一個行注釋
fn = callback_function # 還是行注釋
> 語句
通常每個語句應該獨占一行。不過， 如果測試結果與測試語句在一行放得下， 你也可以將它們放在同一行。如果是if語句， 隻有在沒有else時才能這樣做。特別地，絕不要對 try/except 這樣做，因為try和except不能放在同一行。
2，參考資料
- Google Python編程風格指南
3，文檔修改曆史
- 2016-05-30：V1.0
最後更新：2017-01-09 14:08:09