|
Python 風(fēng)格規(guī)范(Google) 本項目并非 Google 官方項目, 而是由國內(nèi)程序員憑熱情創(chuàng)建和維護(hù),。 如果你關(guān)注的是 Google 官方英文版, 請移步 Google Style Guide 以下代碼中 Yes 表示推薦,，No 表示不推薦。 分號不要在行尾加分號, 也不要用分號將兩條命令放在同一行,。 行長度每行不超過80個字符 以下情況除外：
不要使用反斜杠連接行。 Python會將 圓括號, 中括號和花括號中的行隱式的連接起來 , 你可以利用這個特點. 如果需要, 你可以在表達(dá)式外圍增加一對額外的圓括號,。 推薦: 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'): 如果一個文本字符串在一行放不下, 可以使用圓括號來實現(xiàn)隱式行連接: x = ('這是一個非常長非常長非常長非常長 ' '非常長非常長非常長非常長非常長非常長的字符串') 在注釋中,，如果必要,，將長的URL放在一行上,。 Yes: # See details at # http://www./us/developer/documentation/api/content/v2.0/csv_file_name_extension_full_specification.html No: # See details at # http://www./us/developer/documentation/api/content/\ # v2.0/csv_file_name_extension_full_specification.html 注意上面例子中的元素縮進(jìn); 你可以在本文的 :ref:`縮進(jìn) 括號寧缺毋濫的使用括號 除非是用于實現(xiàn)行連接, 否則不要在返回語句或條件語句中使用括號. 不過在元組兩邊使用括號是可以的. Yes: if foo: bar() while x: x = bar() if x and y: bar() if not x: bar() return foo for (x, y) in dict.items(): ... No: if (x): bar() if not(x): bar() return (foo) 縮進(jìn)用4個空格來縮進(jìn)代碼 絕對不要用tab, 也不要tab和空格混用. 對于行連接的情況, 你應(yīng)該要么垂直對齊換行的元素(見 :ref:`行長度 Yes: # 與起始變量對齊 foo = long_function_name(var_one, var_two, var_three, var_four) # 字典中與起始值對齊 foo = { long_dictionary_key: value1 + value2, ... } # 4 個空格縮進(jìn),，第一行不需要 foo = long_function_name( var_one, var_two, var_three, var_four) # 字典中 4 個空格縮進(jìn) 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) # 字典中沒有處理縮進(jìn) foo = { long_dictionary_key: long_dictionary_value, ... } 空行頂級定義之間空兩行, 方法定義之間空一行 頂級定義之間空兩行, 比如函數(shù)或者類定義. 方法定義, 類定義與第一個方法之間, 都應(yīng)該空一行. 函數(shù)或方法中, 某些地方要是你覺得合適, 就空一行. 空格按照標(biāo)準(zhǔn)的排版規(guī)范來使用標(biāo)點兩邊的空格 括號內(nèi)不要有空格. 按照標(biāo)準(zhǔn)的排版規(guī)范來使用標(biāo)點兩邊的空格 Yes: spam(ham[1], {eggs: 2}, []) No: spam( ham[ 1 ], { eggs: 2 }, [ ] ) 不要在逗號, 分號, 冒號前面加空格, 但應(yīng)該在它們后面加(除了在行尾). Yes: if x == 4: print x, y x, y = y, x No: if x == 4 : print x , y x , y = y , x 參數(shù)列表, 索引或切片的左括號前不應(yīng)加空格. 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). 至于算術(shù)操作符兩邊的空格該如何使用, 需要你自己好好判斷. 不過兩側(cè)務(wù)必要保持一致. Yes: x == 1 No: x<1 當(dāng)'='用于指示關(guān)鍵字參數(shù)或默認(rèn)參數(shù)值時, 不要在其兩側(cè)使用空格. Yes: def complex(real, imag=0.0): return magic(r=real, i=imag) No: def complex(real, imag = 0.0): return magic(r = real, i = imag) 不要用空格來垂直對齊多行間的標(biāo)記, 因為這會成為維護(hù)的負(fù)擔(dān)(適用于:, #, =等): 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文件不必以#!作為文件的開始. 根據(jù) PEP-394 , 程序的main文件應(yīng)該以 #!/usr/bin/python2或者 #!/usr/bin/python3開始. (譯者注: 在計算機科學(xué)中, Shebang (也稱為Hashbang)是一個由井號和嘆號構(gòu)成的字符串行(#!), 其出現(xiàn)在文本文件的第一行的前兩個字符. 在文件中存在Shebang的情況下, 類Unix操作系統(tǒng)的程序載入器會分析Shebang后的內(nèi)容, 將這些內(nèi)容作為解釋器指令, 并調(diào)用該指令, 并將載有Shebang的文件路徑作為該解釋器的參數(shù). 例如, 以指令#!/bin/sh開頭的文件在執(zhí)行時會實際調(diào)用/bin/sh程序.) #!先用于幫助內(nèi)核找到Python解釋器, 但是在導(dǎo)入模塊時, 將會被忽略. 因此只有被直接執(zhí)行的文件中才有必要加入#!. 注釋確保對模塊, 函數(shù), 方法和行內(nèi)注釋使用正確的風(fēng)格 文檔字符串
模塊
函數(shù)和方法
類
塊注釋和行注釋
類如果一個類不繼承自其它類, 就顯式的從object繼承. 嵌套類也一樣. Yes: class SampleClass(object): pass class OuterClass(object): class InnerClass(object): pass class ChildClass(ParentClass): '''Explicitly inherits from another class already.''' No: class SampleClass: pass class OuterClass: class InnerClass: 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 case x = '{}{}'.format(a, b) # use + in this case x = imperative + ', ' + expletive + '!' x = 'name: ' + name + '; score: ' + str(n) 避免在循環(huán)中用+和+=操作符來累加字符串. 由于字符串是不可變的, 這樣做會創(chuàng)建不必要的臨時對象, 并且導(dǎo)致二次方而不是線性的運行時間. 作為替代方案, 你可以將每個子串加入列表, 然后在循環(huán)結(jié)束后用 Yes: items = ['
No: employee_table = '
在同一個文件中, 保持使用字符串引號的一致性. 使用單引號'或者雙引號'之一用以引用字符串, 并在同一文件中沿用. 在字符串內(nèi)可以使用另外一種引號, 以避免在字符串中使用. PyLint已經(jīng)加入了這一檢查. 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.') 為多行字符串使用三重雙引號'''而非三重單引號'''. 當(dāng)且僅當(dāng)項目中使用單引號'來引用字符串時, 才可能會使用三重'''為非文檔字符串的多行字符串來標(biāo)識引用. 文檔字符串必須使用三重雙引號'''. 不過要注意, 通常用隱式行連接更清晰, 因為多行字符串與程序其他部分的縮進(jìn)方式不一致. Yes: print ('This is much nicer.\n' 'Do it this way.\n') No: print '''This is pretty ugly. Don't do this. ''' 文件和sockets在文件和sockets結(jié)束時, 顯式的關(guān)閉它. 除文件外, sockets或其他類似文件的對象在沒有必要的情況下打開, 會有許多副作用, 例如:
而且, 幻想當(dāng)文件對象析構(gòu)時, 文件和sockets會自動關(guān)閉, 試圖將文件對象的生命周期和文件的狀態(tài)綁定在一起的想法, 都是不現(xiàn)實的. 因為有如下原因:
推薦使用 'with'語句 以管理文件: with open('hello.txt') as hello_file: for line in hello_file: print line 對于不支持使用'with'語句的類似文件的對象,使用 contextlib.closing(): import contextlibwith contextlib.closing(urllib.urlopen('http://www./')) as front_page: for line in front_page: print line Legacy AppEngine 中Python 2.5的代碼如使用'with'語句, 需要添加 'from __future__ import with_statement'. TODO注釋為臨時代碼使用TODO注釋, 它是一種短期解決方案. 不算完美, 但夠好了. TODO注釋應(yīng)該在所有開頭處包含'TODO'字符串, 緊跟著是用括號括起來的你的名字, email地址或其它標(biāo)識符. 然后是一個可選的冒號. 接著必須有一行注釋, 解釋要做什么. 主要目的是為了有一個統(tǒng)一的TODO格式, 這樣添加注釋的人就可以搜索到(并可以按需提供更多細(xì)節(jié)). 寫了TODO注釋并不保證寫的人會親自解決問題. 當(dāng)你寫了一個TODO, 請注上你的名字. # TODO([email protected]): Use a '*' here for string repetition.# TODO(Zeke) Change this to use relations. 如果你的TODO是'將來做某事'的形式, 那么請確保你包含了一個指定的日期('2009年11月解決')或者一個特定的事件('等到所有的客戶都可以處理XML請求就移除這些代碼'). 導(dǎo)入格式每個導(dǎo)入應(yīng)該獨占一行 Yes: import os import sys No: import os, sys 導(dǎo)入總應(yīng)該放在文件頂部, 位于模塊注釋和文檔字符串之后, 模塊全局變量和常量之前. 導(dǎo)入應(yīng)該按照從最通用到最不通用的順序分組:
每種分組中, 應(yīng)該根據(jù)每個模塊的完整包路徑按字典序排序, 忽略大小寫. import foofrom foo import barfrom foo.bar import bazfrom foo.bar import Quuxfrom Foob import ar 語句通常每個語句應(yīng)該獨占一行 不過, 如果測試結(jié)果與測試語句在一行放得下, 你也可以將它們放在同一行. 如果是if語句, 只有在沒有else時才能這樣做. 特別地, 絕不要對 Yes: if foo: bar(foo) No: if foo: bar(foo) else: baz(foo) try: bar(foo) except ValueError: baz(foo) try: bar(foo) except ValueError: baz(foo) 訪問控制在Python中, 對于瑣碎又不太重要的訪問函數(shù), 你應(yīng)該直接使用公有變量來取代它們, 這樣可以避免額外的函數(shù)調(diào)用開銷. 當(dāng)添加更多功能時, 你可以用屬性(property)來保持語法的一致性. (譯者注: 重視封裝的面向?qū)ο蟪绦騿T看到這個可能會很反感, 因為他們一直被教育: 所有成員變量都必須是私有的! 其實, 那真的是有點麻煩啊. 試著去接受Pythonic哲學(xué)吧) 另一方面, 如果訪問更復(fù)雜, 或者變量的訪問開銷很顯著, 那么你應(yīng)該使用像 命名module_name, package_name, ClassName, method_name, ExceptionName, function_name, GLOBAL_VAR_NAME, instance_var_name, function_parameter_name, local_var_name. 應(yīng)該避免的名稱
命名約定
Python之父Guido推薦的規(guī)范
Main即使是一個打算被用作腳本的文件, 也應(yīng)該是可導(dǎo)入的. 并且簡單的導(dǎo)入不應(yīng)該導(dǎo)致這個腳本的主功能(main functionality)被執(zhí)行, 這是一種副作用. 主功能應(yīng)該放在一個main()函數(shù)中. 在Python中, pydoc以及單元測試要求模塊必須是可導(dǎo)入的. 你的代碼應(yīng)該在執(zhí)行主程序前總是檢查 def main(): ...if __name__ == '__main__': main() 所有的頂級代碼在模塊導(dǎo)入時都會被執(zhí)行. 要小心不要去調(diào)用函數(shù), 創(chuàng)建對象, 或者執(zhí)行那些不應(yīng)該在使用pydoc時執(zhí)行的操作. |
|
|
