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） 不要用空格來垂直對齊多行間的標記，由於這會成爲維護的負擔（適用於:，#，=等）

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

1. 在類、函數的定義間加空行；

2. 在 import 不一樣種類的模塊間加空行；

3. 在函數中的邏輯段落間加空行，即把相關的代碼緊湊寫在一塊兒，做爲一個邏輯段落，段落間以空行分隔；

> 斷行
儘管如今的寬屏顯示器已經能夠單屏顯示超過 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);

> 字符串

1. 避免在循環中用+和+=操做符來累加字符串。因爲字符串是不可變的，這樣作會建立沒必要要的臨時對象，而且致使二次方而不是線性的運行時間。做爲替代方案，你能夠將每一個子串加入列表，而後在循環結束後用 .join 鏈接列表。（也能夠將每一個子串寫入一個 cStringIO.StringIO 緩存中）

2. 爲多行字符串使用三重雙引號而非三重單引號。不過要注意, 一般用隱式行鏈接更清晰，由於多行字符串與程序其餘部分的縮進方式不一致。

> 命名
一致的命名能夠給開發人員減小許多麻煩，而恰如其分的命名則能夠大幅提升代碼的可讀性，下降維護成本。

>> 常量
常量名全部字母大寫，由下劃線鏈接各個單詞，如

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 都採用了系統保留字命名法。

>> 導入格式

1. import 的次序，先 import Python 內置模塊，再 import 第三方模塊，最後 import 本身開發的項目中的其它模塊；這幾種模塊用空行分隔開來。

2. 每一個import應該獨佔一行。

3. 不要使用 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-06-02：V1.0