Python 之 風格規範（Google ）

標籤：set   idt   des   風格   lex   檔案   操作   電腦   指示   

開頭先mark一下網址：goole官網

任何語言的程式員，編寫出符合規範的代碼，是開始程式生涯的第一步。

一、分號

不要在行尾加分號, 也不要用分號將兩條命令放在同一行。

二、行長度

　每行不超過80個字元

例外:

1. 長的匯入模組語句
2. 注釋裡的URL

不要使用反斜線串連行.

Python會將 圓括弧, 中括弧和花括弧中的行隱式的串連起來 , 你可以利用這個特點. 如果需要, 你可以在運算式外圍增加一對額外的圓括弧.

Yes: foo_bar(self, width, height, color=‘black‘, design=None, x=‘foo‘,             emphasis=None, highlight=0)     if (width == 0 and height == 0 and         color == ‘red‘ and emphasis == ‘strong‘):

如果一個文本字串在一行放不下, 可以使用圓括弧來實現隱式行串連

x = (‘This will build a very long long ‘     ‘long long long long long long string‘)

在注釋中，如果必要，將長的URL放在一行上。

Yes: # See details at # http://www.example.com/us/developer/documentation/api/content/v2.0/csv_file_name_extension_full_specification.html

No:  # See details at     # http://www.example.com/us/developer/documentation/api/content/\     # v2.0/csv_file_name_extension_full_specification.html

三、括弧

寧缺毋濫的使用括弧

除非是用於實現行串連, 否則不要在返回語句或條件陳述式中使用括弧. 不過在元組兩邊使用括弧是可以的.

四、縮排

用4個空格來縮排代碼

絕對不要用tab, 也不要tab和空格混用.

對於行串連的情況, 你應該要麼垂直對齊換行的元素(見 行長度 部分的樣本),或者使用4空格的懸掛式縮排(這時第一行不應該有參數):

五、空行

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

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

六、空格

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

1. 括弧內不要有空格.
2. 不要在逗號, 分號, 冒號前面加空格, 但應該在它們後面加(除了在行尾).
3. 參數列表, 索引或切片的左括弧前不應加空格.
4. 在二元操作符兩邊都加上一個空格, 比如賦值(=), 比較(==, <, >, !=, <>, <=, >=, in, not in, is, is not), 布爾(and, or, not). 至於算術操作符兩邊的空格該如何使用, 需要你自己好好判斷. 不過兩側務必要保持一致.
5. 當’=’用於指示關鍵字參數或預設參數值時, 不要在其兩側使用空格.
6. 不要用空格來垂直對齊多行間的標記, 因為這會成為維護的負擔(適用於:, #, =等)

七、Shebang

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

(譯者注: 在電腦科學中, Shebang (也稱為Hashbang)是一個由井號和歎號構成的字串行(#!), 其出現在文字檔的第一行的前兩個字元. 在檔案中存在Shebang的情況下, 類Unix作業系統的程式載入器會分析Shebang後的內容, 將這些內容作為解譯器指令, 並調用該指令, 並將載有Shebang的檔案路徑作為該解譯器的參數. 例如, 以指令#!/bin/sh開頭的檔案在執行時會實際調用/bin/sh程式.)

#!先用於協助核心找到Python解譯器, 但是在匯入模組時, 將會被忽略. 因此只有被直接執行的檔案中才有必要加入#!.

八、注釋

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

塊注釋和行注釋

最需要寫注釋的是代碼中那些技巧性的部分. 如果你在下次 代碼審查 的時候必須解釋一下, 那麼你應該現在就給它寫注釋. 對於複雜的操作, 應該在其操作開始前寫上若干行注釋. 對於不是一目瞭然的代碼, 應在其行尾添加註釋.

為了提高可讀性, 注釋應該至少離開代碼2個空格.

另一方面, 絕不要描述代碼. 假設閱讀代碼的人比你更懂Python, 他只是不知道你的代碼要做什麼.

九、類

如果一個類不繼承自其它類, 就顯式的從object繼承. 嵌套類也一樣.

繼承自 object 是為了使屬性(properties)正常工作, 並且這樣可以保護你的代碼, 使其不受 PEP-3000 的一個特殊的潛在不相容性影響. 這樣做也定義了一些特殊的方法, 這些方法實現了對象的預設語義, 包括

__new__, __init__, __delattr__, __getattribute__, __setattr__, __hash__, __repr__, and __str__

十、字串

即使參數都是字串, 使用%操作符或者格式化方法格式化字串. 不過也不能一概而論, 你需要在+和%之間好好判定.

避免在迴圈中用+和+=操作符來累加字串. 由於字串是不可變的, 這樣做會建立不必要的臨時對象, 並且導致二次方而不是線性已耗用時間. 作為替代方案, 你可以將每個子串加入列表, 然後在迴圈結束後用 .join 串連列表. (也可以將每個子串寫入一個 cStringIO.StringIO 緩衝中.)

十一、檔案和sockets

在檔案和sockets結束時, 顯式的關閉它.

十二、TODO注釋

為臨時代碼使用TODO注釋, 它是一種短期解決方案. 不算完美, 但夠好了.

十三、匯入格式

每個匯入應該獨佔一行

匯入總應該放在檔案頂部, 位於模組注釋和文檔字串之後, 模組全域變數和常量之前. 匯入應該按照從最通用到最不通用的順序分組:

1. 標準庫匯入
2. 第三方庫匯入
3. 應用程式指定匯入

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

十四、語句

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

不過, 如果測試結果與測試語句在一行放得下, 你也可以將它們放在同一行.

如果是if語句, 只有在沒有else時才能這樣做. 特別地, 絕不要對 try/except 這樣做, 因為try和except不能放在同一行.

十五、存取控制

在Python中, 對於瑣碎又不太重要的訪問函數, 你應該直接使用公有變數來取代它們, 這樣可以避免額外的函數調用開銷. 當添加更多功能時, 你可以用屬性(property)來保持文法的一致性.(譯者注: 重視封裝的物件導向程式員看到這個可能會很反感, 因為他們一直被教育: 所有成員變數都必須是私人的! 其實, 那真的是有點麻煩啊. 試著去接受Pythonic哲學吧)

十六、命名

module_name, package_name, ClassName, method_name, ExceptionName, function_name, GLOBAL_VAR_NAME, instance_var_name, function_parameter_name, local_var_name.

應該避免的名稱

1. 單字元名稱, 除了計數器和迭代器.
2. 包/模組名中的連字號(-)
3. 雙底線開頭並結尾的名稱(Python保留, 例如__init__)

命名規範

1. 所謂”內部(Internal)”表示僅模組內可用, 或者, 在類內是保護或私人的.
2. 用單底線(_)開頭表示模組變數或函數是protected的(使用import * from時不會包含).
3. 用雙底線(__)開頭的執行個體變數或方法表示類內私人.
4. 將相關的類和頂級函數放在同一個模組裡. 不像Java, 沒必要限制一個類一個模組.
5. 對類名使用大寫字母開頭的單詞(如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 之 風格規範（Google ）