Python轉載[編碼規範]

 

轉自：http://blog.csdn.net/lanphaday/article/details/6601123 

但是有些如果與python內建的類庫有衝突的做了適當的修改。 

 

1 編碼

>>所有的 Python 指令檔都應在檔案頭標上如下標識或其相容格式的標識： # -*- coding:utf-8 -*-  >>設定編輯器，預設建立或儲存為utf-8格式。

 

2 注釋>>業界普遍認同 Python 的注釋分為兩種的概念，一種是由 # 開頭的“真正的”注釋，另一種是 docstrings。前者表明為何選擇當前實現以及這種實現的原理和痛點，後者表明如何使用這個包、模組、類、函數（方法），甚至包括使用樣本和單元測試。>>堅持適當注釋原則。對不存在技術痛點的代碼堅持不注釋，對存在技術痛點的代碼必須注釋。但與注釋不同，推薦對每一個包、模組、類、函數（方法）寫 docstrings，除非代碼一目瞭然，非常簡單。 

3 格式縮排>>Python依賴縮排來確定代碼塊的層次，行首空白符主要有兩種：tab 和空格，但嚴禁兩者混用。>>使用4個空格的tab進行縮排，保持與python類庫一致。

 

4 空格>>空格在Python代碼中是有意義的，因為Python的文法依賴於縮排，在行首的空格稱為前置空格。在這一節不討論前置空格相關的內容，只討論非前置空格。非前置空格在 Python 代碼中沒有意義，但適當地加入非前置空格可以增進代碼的可讀性。>>在二元算術、邏輯運算子前後加空格，如：a = b + c  >> “:”用在行尾時前後皆不加空格，如分枝、迴圈、函數和類定義語言；用在非行尾時兩端加空格，如 dict 對象的定義：d = {'key' : 'value'}  >>括弧（含圓括弧、方括弧和花括弧）前後不加空格，如：do_something(arg1, arg2)  而不是do_something( arg1, arg2 )  逗號後面加一個空格，前面不加空格；

>>函數中具名引數中的=前後不需要加空格，例如：
def parse(fp=None, environ=os.environ, keep_blank_values=0, strict_parsing=0): pass

5 空行>>適當的空行有利於增加代碼的可讀性，加空行可以參考如下幾個準則：在類、函數的定義間加空行；在import不同種類的模組間加空行；在函數中的邏輯段落間加空行，即把相關的代碼緊湊寫在一起，作為一個邏輯段落，段落間以空行分隔；

6 斷行>>儘管現在的寬屏顯示器已經可以單屏顯示超過 256 列字元，但本規範仍然堅持行的最大長度不得超過78個字元的標準(我覺的notepad++預設值為100比較合適)。摺疊長行的方法有以下幾種方法：為長變數名換一個短名，如：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_name2  >>在括弧（包括圓括弧、方括弧和花括弧）內換行，如：class Edit(Widget):    def __init__(self, parent, width,        font = FONT, color = BLACK, pos = POS, style = 0): # 注意：多一層縮排      pass  或：very_very_very_long_variable_name = Edit(parent,    width,    font,    color,    pos) # 注意：多一層縮排  do_sth_with(very_very_very_long_variable_name)  

 

>>如果行長到連第一個括弧內的參數都放不下，則每個元素都單獨佔一行：very_very_very_long_variable_name = ui.widgets.Edit(    panrent,    width,    font,    color,    pos) # 注意：多一層縮排  do_sth_with(very_very_very_long_variable_name)  

 

>>在長行加入續行符強行斷行，斷行的位置應在操作符前，且換行後多一個縮排，以使維護人員看代碼的時候看到程式碼首即可判定這裡存在換行，如：if color == WHITE or color == BLACK \      or color == BLUE: # 注意 or 操作符在新行的行首而不是舊行的行尾，上一行的續行符不可省略    do_something(color);  else:    do_something(DEFAULT_COLOR);  

 

7 命名一致的命名可以給開發人員減少許多麻煩，而恰如其分的命名則可以大幅提高代碼的可讀性，降低維護成本。 >>常量常量名所有字母大寫，由底線串連各個單詞，如：WHITE = 0xffffffff  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   

>>包

包的命名規範與模組相同。

8 縮寫>>命名應當盡量使用全拼字的單詞，縮寫的情況有如下兩種：常用的縮寫，如 XML、ID等，在命名時也應只大寫首字母，如：class XmlParser(object):pass  

 

>>命名中含有長單詞，對某個單詞進行縮寫。這時應使用約定成俗的縮寫方式，如去除母音、包含輔音的首字元等方式，例如：function 縮寫為 fntext 縮寫為 txtobject 縮寫為 objcount 縮寫為 cntnumber 縮寫為 num，等。

 

>>特定命名方式主要是指 __xxx__ 形式的系統保留字命名法。項目中也可以使用這種命名，它的意義在於這種形式的變數是唯讀，這種形式的類成員函數一般都有特定的含義，自訂時需要確保不要與系統的衝突，只有在確實需要的時候才重載系統保留的這些函數。如：class Base(object):    def __init__(self, id, parent = None):      self.__id__ = id      self.__parent__ = parent    def __message__(self, msgid):  pass其中 __id__、__parent__ 和 __message__ 都採用了系統保留字命名法。

 

9 語句>>importimport 語句有以下幾個原則需要遵守：import 的次序，先import Python 內建模組，再import第三方模組，最後import自己開發的項目中的其它模組；這幾種模組中用空行分隔開來。一條import語句import一個模組。

 

當從模組中import多個對象且超過一行時，使用如下斷行法（此文法 py2.5 以上版本才支援）：from module import (obj1, obj2, obj3, obj4,      obj5, obj6)  

 

不要使用 from module import *，除非是import常量定義模組或其它你確保不會出現命名空間衝突的模組。

 

>>賦值對於指派陳述式，主要是不要做無謂的對齊，如：a        = 1                  # 這是一個行注釋  variable = 2                  # 另一個行注釋  fn       = callback_function  # 還是行注釋  沒有必要做這種對齊，原因有兩點：

一是這種對齊會打亂編程時的注意力，大腦要同時處理兩件事（編程和對齊）；

二是以後閱讀和維護都很困難，因為人眼的橫向視野很窄，把三個欄位看成一行很困難，而且維護時要增加一個更長的變數名也會破壞對齊。

直接這樣寫為佳：

a = 1 # 這是一個行注釋  variable = 2 # 另一個行注釋  fn = callback_function # 還是行注釋  >>分支和迴圈對於分支和迴圈，有如下幾點需要注意的：不要寫成一行，如：if not flg: pass  和for i in xrange(10): print i  都不是好代碼，應寫成if not flg:    pass  for i in xrange(10):    print i  註：本文檔中出現寫成一行的例子是因為排版的原因，不得作為編碼中不斷行的依據。

 

>>條件運算式的編寫應該足夠 pythonic，如以下形式的條件運算式是拙劣的：if not len(alist) == 0: do_something()  if not alist == []: do_something()  if not s == "": do_something()  if not var == None: do_something()  if not var == False: do_something()  因為python中None，0，''，[]等預設為False，上面的語句應該寫成：if seq: do_somethin() # 注意，這裡命名也更改了  if var: do_something()  用得著的時候多使用迴圈語句的 else 分句，以簡化代碼。

 

完！