單字符名稱, 除了計數器和迭代器.

包/模塊名中的連字符(-)

雙下劃線開頭并結尾的名稱(Python保留, 例如

命名約定

所謂"內部(Internal)"表示僅模塊內可用, 或者, 在類內是保護或私有的.

用單下劃線(_)開頭表示模塊變量或函數是protected的(使用import * from時不會包含).

用雙下劃線(__)開頭的實例變量或方法表示類內私有.

將相關的類和頂級函數放在同一個模塊里. 不像Java, 沒必要限制一個類一個模塊.

對類名使用大寫字母開頭的單詞(如CapWords, 即Pascal風格), 但是模塊名應該用小寫加下劃線的方式(如lower_with_under.py). 盡管已經有很多現存的模塊使用類似于CapWords.py這樣的命名, 但現在已經不鼓勵這樣做, 因為如果模塊名碰巧和類名一致, 這會讓人困擾.

Python之父Guido推薦的規范

Type

Public

Internal

Modules

lower_with_under

_lower_with_under

Packages

lower_with_under

Classes

CapWords

_CapWords

Exceptions

CapWords

Functions

lower_with_under()

_lower_with_under()

Global/Class Constants

CAPS_WITH_UNDER

_CAPS_WITH_UNDER

Global/Class Variables

lower_with_under

_lower_with_under

Instance Variables

lower_with_under

_lower_with_under (protected) or __lower_with_under (private)

Method Names

lower_with_under()

_lower_with_under() (protected) or __lower_with_under() (private)

Function/Method Parameters

lower_with_under

Local Variables

lower_with_under

Main

即使是一個打算被用作腳本的文件, 也應該是可導入的. 并且簡單的導入不應該導致這個腳本的主功能(main functionality)被執行, 這是一種副作用. 主功能應該放在一個main()函數中.

在Python中, pydoc以及單元測試要求模塊必須是可導入的. 你的代碼應該在執行主程序前總是檢查?if __name__ == '__main__'?, 這樣當模塊被導入時主程序就不會被執行.

defmain():...if__name__ =='__main__':main()

所有的頂級代碼在模塊導入時都會被執行. 要小心不要去調用函數, 創建對象, 或者執行那些不應該在使用pydoc時執行的操作.

二、模塊導入格式規范

導入格式

每個導入應該獨占一行

Yes:importos importsys

No:importos,sys

導入總應該放在文件頂部, 位于模塊注釋和文檔字符串之后, 模塊全局變量和常量之前. 導入應該按照從最通用到最不通用的順序分組:

標準庫導入

第三方庫導入

應用程序指定導入

每種分組中, 應該根據每個模塊的完整包路徑按字典序排序, 忽略大小寫.

importfoo

fromfoo importbar fromfoo.bar importbaz fromfoo.bar importQuuxfromFoobimportar

三.縮進

縮進

用4個空格來縮進代碼

絕對不要用tab, 也不要tab和空格混用. 對于行連接的情況, 你應該要么垂直對齊換行的元素(見 :ref:`行長度 ` 部分的示例), 或者使用4空格的懸掛式縮進(這時第一行不應該有參數):

Yes:# 與起始變量對齊foo =long_function_name(var_one,var_two,var_three,var_four)# 字典中與起始值對齊foo ={long_dictionary_key:value1 +value2,...}# 4 個空格縮進，第一行不需要foo =long_function_name(var_one,var_two,var_three,var_four)# 字典中 4 個空格縮進foo ={long_dictionary_key:long_dictionary_value,...}

No:# 第一行有空格是禁止的foo =long_function_name(var_one,var_two,var_three,var_four)# 2 個空格是禁止的foo =long_function_name(var_one,var_two,var_three,var_four)# 字典中沒有處理縮進foo ={long_dictionary_key:long_dictionary_value,...}

空行

頂級定義之間空兩行, 方法定義之間空一行

頂級定義之間空兩行, 比如函數或者類定義. 方法定義, 類定義與第一個方法之間, 都應該空一行. 函數或方法中, 某些地方要是你覺得合適, 就空一行.

空格

按照標準的排版規范來使用標點兩邊的空格

括號內不要有空格.

按照標準的排版規范來使用標點兩邊的空格

Yes:spam(ham[1],{eggs:2},[])

No:spam(ham[1],{eggs:2},[])

不要在逗號, 分號, 冒號前面加空格, 但應該在它們后面加(除了在行尾).

Yes:ifx ==4:printx,y x,y =y,x

No:ifx ==4:printx ,y x ,y =y ,x

參數列表, 索引或切片的左括號前不應加空格.

Yes:spam(1)

no:spam (1)

Yes:dict['key']=list[index]

No:dict ['key']=list [index]

在二元操作符兩邊都加上一個空格, 比如賦值(=), 比較(==, , !=, <>, <=, >=, in, not in, is, is not), 布爾(and, or, not). 至于算術操作符兩邊的空格該如何使用, 需要你自己好好判斷. 不過兩側務必要保持一致.

Yes:x ==1

No:x<1

當'='用于指示關鍵字參數或默認參數值時, 不要在其兩側使用空格.

Yes:defcomplex(real,imag=0.0):returnmagic(r=real,i=imag)

No:defcomplex(real,imag =0.0):returnmagic(r =real,i =imag)

不要用空格來垂直對齊多行間的標記, 因為這會成為維護的負擔(適用于:, #, =等):

Yes:foo =1000# 注釋long_name =2# 注釋不需要對齊dictionary ={"foo":1,"long_name":2,}

No:foo =1000# 注釋long_name =2# 注釋不需要對齊dictionary ={"foo":1,"long_name":2,}

Shebang

大部分.py文件不必以#!作為文件的開始. 根據?PEP-394?, 程序的main文件應該以 #!/usr/bin/python2或者 #!/usr/bin/python3開始.

(譯者注: 在計算機科學中,?Shebang?(也稱為Hashbang)是一個由井號和嘆號構成的字符串行(#!), 其出現在文本文件的第一行的前兩個字符. 在文件中存在Shebang的情況下, 類Unix操作系統的程序載入器會分析Shebang后的內容, 將這些內容作為解釋器指令, 并調用該指令, 并將載有Shebang的文件路徑作為該解釋器的參數. 例如, 以指令#!/bin/sh開頭的文件在執行時會實際調用/bin/sh程序.)

#!先用于幫助內核找到Python解釋器, 但是在導入模塊時, 將會被忽略. 因此只有被直接執行的文件中才有必要加入#!.

注釋

確保對模塊, 函數, 方法和行內注釋使用正確的風格

文檔字符串

Python有一種獨一無二的的注釋方式: 使用文檔字符串. 文檔字符串是包, 模塊, 類或函數里的第一個語句. 這些字符串可以通過對象的__doc__成員被自動提取, 并且被pydoc所用. (你可以在你的模塊上運行pydoc試一把, 看看它長什么樣). 我們對文檔字符串的慣例是使用三重雙引號"""(?PEP-257?). 一個文檔字符串應該這樣組織: 首先是一行以句號, 問號或驚嘆號結尾的概述(或者該文檔字符串單純只有一行). 接著是一個空行. 接著是文檔字符串剩下的部分, 它應該與文檔字符串的第一行的第一個引號對齊. 下面有更多文檔字符串的格式化規范.

模塊

每個文件應該包含一個許可樣板. 根據項目使用的許可(例如, Apache 2.0, BSD, LGPL, GPL), 選擇合適的樣板.

函數和方法

下文所指的函數,包括函數, 方法, 以及生成器.

一個函數必須要有文檔字符串, 除非它滿足以下條件:

外部不可見

非常短小

簡單明了

文檔字符串應該包含函數做什么, 以及輸入和輸出的詳細描述. 通常, 不應該描述"怎么做", 除非是一些復雜的算法. 文檔字符串應該提供足夠的信息, 當別人編寫代碼調用該函數時, 他不需要看一行代碼, 只要看文檔字符串就可以了. 對于復雜的代碼, 在代碼旁邊加注釋會比使用文檔字符串更有意義.

關于函數的幾個方面應該在特定的小節中進行描述記錄， 這幾個方面如下文所述. 每節應該以一個標題行開始. 標題行以冒號結尾. 除標題行外, 節的其他內容應被縮進2個空格.

Args:

列出每個參數的名字, 并在名字后使用一個冒號和一個空格, 分隔對該參數的描述.如果描述太長超過了單行80字符,使用2或者4個空格的懸掛縮進(與文件其他部分保持一致). 描述應該包括所需的類型和含義. 如果一個函數接受*foo(可變長度參數列表)或者**bar (任意關鍵字參數), 應該詳細列出*foo和**bar.

Returns: (或者 Yields: 用于生成器)

描述返回值的類型和語義. 如果函數返回None, 這一部分可以省略.

Raises:

列出與接口有關的所有異常.

deffetch_bigtable_rows(big_table,keys,other_silly_variable=None):"""Fetches rows from a Bigtable. Retrieves rows pertaining to the given keys from the Table instance represented by big_table. Silly things may happen if other_silly_variable is not None. Args: big_table: An open Bigtable Table instance. keys: A sequence of strings representing the key of each table row to fetch. other_silly_variable: Another optional variable, that has a much longer name than the other args, and which does nothing. Returns: A dict mapping keys to the corresponding table row data fetched. Each row is represented as a tuple of strings. For example: {'Serak': ('Rigel VII', 'Preparer'), 'Zim': ('Irk', 'Invader'), 'Lrrr': ('Omicron Persei 8', 'Emperor')} If a key from the keys argument is missing from the dictionary, then that row was not found in the table. Raises: IOError: An error occurred accessing the bigtable.Table object. """pass

字符串

Yes:x =a +b x ='%s, %s!'%(imperative,expletive)x ='{}, {}!'.format(imperative,expletive)x ='name: %s; score: %d'%(name,n)x ='name: {}; score: {}'.format(name,n)

No:x ='%s%s'%(a,b)# use + in this casex ='{}{}'.format(a,b)# use + in this casex =imperative +', '+expletive +'!'x ='name: '+name +'; score: '+str(n)

避免在循環中用+和+=操作符來累加字符串. 由于字符串是不可變的, 這樣做會創建不必要的臨時對象, 并且導致二次方而不是線性的運行時間. 作為替代方案, 你可以將每個子串加入列表, 然后在循環結束后用?.join?連接列表. (也可以將每個子串寫入一個?cStringIO.StringIO?緩存中.)

Yes:items =['

%s, %s

')employee_table =''.join(items)

No:employee_table ='

%s, %s

'

在同一個文件中, 保持使用字符串引號的一致性. 使用單引號'或者雙引號"之一用以引用字符串, 并在同一文件中沿用. 在字符串內可以使用另外一種引號, 以避免在字符串中使用. PyLint已經加入了這一檢查.

Yes:Python('Why are you hiding your eyes?')Gollum("I'm scared of lint errors.")Narrator('"Good!" thought a happy Python reviewer.')

No:Python("Why are you hiding your eyes?")Gollum('The lint. It burns. It burns us.')Gollum("Always the great lint. Watching. Watching.")

為多行字符串使用三重雙引號"""而非三重單引號'''. 當且僅當項目中使用單引號'來引用字符串時, 才可能會使用三重'''為非文檔字符串的多行字符串來標識引用. 文檔字符串必須使用三重雙引號""". 不過要注意, 通常用隱式行連接更清晰, 因為多行字符串與程序其他部分的縮進方式不一致.

Yes:print("This is much nicer.\n""Do it this way.\n")

No:print"""This is pretty ugly. Don't do this. """

語句

通常每個語句應該獨占一行

不過, 如果測試結果與測試語句在一行放得下, 你也可以將它們放在同一行. 如果是if語句, 只有在沒有else時才能這樣做. 特別地, 絕不要對?try/except?這樣做, 因為try和except不能放在同一行.

Yes:iffoo:bar(foo)

if not xx:

pass

else:

pass

No:iffoo:bar(foo)else:baz(foo)try:bar(foo)exceptValueError:baz(foo)try:bar(foo)exceptValueError:baz(foo)

訪問控制

在Python中, 對于瑣碎又不太重要的訪問函數, 你應該直接使用公有變量來取代它們, 這樣可以避免額外的函數調用開銷. 當添加更多功能時, 你可以用屬性(property)來保持語法的一致性.

(譯者注: 重視封裝的面向對象程序員看到這個可能會很反感, 因為他們一直被教育: 所有成員變量都必須是私有的! 其實, 那真的是有點麻煩啊. 試著去接受Pythonic哲學吧)

另一方面, 如果訪問更復雜, 或者變量的訪問開銷很顯著, 那么你應該使用像?get_foo()?和?set_foo()?這樣的函數調用. 如果之前的代碼行為允許通過屬性(property)訪問 , 那么就不要將新的訪問函數與屬性綁定. 這樣, 任何試圖通過老方法訪問變量的代碼就沒法運行, 使用者也就會意識到復雜性發生了變化.

總結

以上是生活随笔為你收集整理的python语言入门e_python 语言学入门第一课必看：编码规范的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。