簡明 Python 程式設計規範

2021-09-07 22:46:03 字數 4947 閱讀 6779

編碼

業界普遍認同 python 的注釋分為兩種的概念,一種是由 # 開頭的「真正的」注釋,另一種是 docstrings。前者表明為何選擇當前實現以及這種實現的原理和難點,後者表明如何使用這個包、模組、類、函式(方法),甚至包括使用示例和單元測試。

堅持適當注釋原則。對不存在技術難點的**堅持不注釋,對存在技術難點的**必須注釋。但與注釋不同,推薦對每乙個包、模組、類、函式(方法)寫 docstrings,除非**一目了然,非常簡單。

縮排

python 依賴縮進來確定**塊的層次,行首空白符主要有兩種:tab 和空格,但嚴禁兩者混用。如果使用 tab 縮排,設定 tab 為 4 個空格。

公司內部推薦使用 4 個空格的 tab 進行縮排。

空格

空格在 python **中是有意義的,因為 python 的語法依賴於縮排,在行首的空格稱為前導空格。在這一節不討論前導空格相關的內容,只討論非前導空格。非前導空格在 python **中沒有意義,但適當地加入非前導空格可以增進**的可讀性。

1) 在二元算術、邏輯運算子前後加空格:如 a = b + c;

2) 在一元字首運算子後不加空格,如 if !***: pass;

3) 「:」用在行尾時前後皆不加空格,如分枝、迴圈、函式和類定義語言;用在非行尾時兩端加空格,如 dict 物件的定義 d = 。

4) 括號(含圓括號、方括號和花括號)前後不加空格,如 do_something(arg1, arg2),而不是 do_something( arg1, arg2 );

5) 逗號後面加乙個空格,前面不加空格;s

空行

適當的空行有利於增加**的可讀性,加空行可以參考如下幾個準則:

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, /

font, /

color, /

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

object 縮寫為 obj

count 縮寫為 cnt

number 縮寫為 num,等。

特定命名方式

主要是指 __***__ 形式的系統保留字命名法。專案中也可以使用這種命名,它的意義在於這種形式的變數是唯讀的,這種形式的類成員函式盡量不要過載。如 

class base(object):

def __init__(self, id, parent = none):

self.__id__ = id

self.__parent__ = parent

def __message__(self, msgid):

# …略

其中 __id__、__parent__ 和 __message__ 都採用了系統保留字命名法。

語句

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 !***: pass 和 for i in xrange(10): print i都不是好**,應寫成

if !***:

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 分句,以簡化**。

已有**

對於專案中已有的**,可能因為歷史遺留原因不符合本規範,應當看作可以容忍的特例,允許存在;但不應在新的**中延續舊的風格。

對於第三方模組,可能不符合本規範,也應看作可以容忍的特例,允許存在;但不應在新的**中使用第三方模組的風格。

tab 與空格混用的縮排是不可容忍的,在執行專案時應使用 –t 或 –tt 選項排查這種可能性存在。出現混用的情況時,如果是公司開發的基礎類庫**,應當通知類庫維護人員修改;第三方模組則可以通過提交 patch 等方式敦促開發者修正問題。

簡明 Python 程式設計規範v2

賴勇浩 注 之前發布一篇 簡明 python 程式設計規範 見 本是我給當時所在的公司制定的,發表到部落格的時候,對齊等問題都有一些錯誤,還包括一些錯別字。到後來,我又有做過修正。大概在 2010 年 8 年,我又由 c 開發轉到 python 開發,便在那之前的基礎上潤飾和完善,形成第二版。前段時...

Python程式設計規範

1,python程式設計規範 編碼 所有的 python 指令碼檔案都應在檔案頭標上 coding utf 8 用於設定編輯器,預設儲存為 utf 8 格式。注釋 業界普遍認同 python 的注釋分為兩種,堅持適當注釋原則。對不存在技術難點的 堅持不注釋,對存在技術難點的 必須注釋。但與注釋不同,...

Python程式設計規範

簡單總結一下 類名 首字母大寫,如 myclass,內部類可以使用額外的前導下劃線。函式 方法名 小寫 下劃線 函式和方法的引數 如果函式的引數名稱和保留關鍵字衝突,通常加乙個字尾下劃線 全域性變數 避免使用全域性變數 變數 小寫,使用下劃線連線各個單詞。如 this is a variable 1...