python/django編碼規範（code style）

轉自：http://pythoner.org/wiki/10/

編碼

    全部的 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） 逗號後面加一個空格，前面不加空格；
空行
    適當的空行有利於增長代碼的可讀性，加空行能夠參考以下幾個準則：
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, \
                                                                                    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
number 縮寫爲 num，等。
特定命名方式
    主要是指 __xxx__ 形式的系統保留字命名法。項目中也可使用這種命名，它的意義在於這種形式的變量是隻讀的，這種形式的類成員函數儘可能不要重載。如 
class Base(object):
    def __init__(self, id, parent = None):
        self.__id__ = id
        self.__parent__ = parent
    def __message__(self, msgid):
        # …略語句
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 分句，以簡化代碼。
其中 __id__、__parent__ 和 __message__ 都採用了系統保留字命名法。