歡迎光臨
每天分享高質量文章
當前位置：知識星球 > 後端 > 正文

Google Python 編碼規範指南

2019-05-20 分類：後端 閱讀(321) 評論(0)

（點選上方快速關註並設定為星標，一起學Python）

來源：KotlinPython   連結：

https://mp.weixin.qq.com/s/-aM6AJ2oUnMYjmanbLH0LA

我是PythonGao。 一名微軟工程師。今天給大家分享一下Google Python 程式設計規範。適合入門者學習。

分號

 

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

行長度

每行不超過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







註意上面例子中的元素縮排; 你可以在本文的 縮排 部分找到解釋.


括號


寧缺毋濫的使用括號


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


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)


 


 


縮排




用4個空格來縮排程式碼


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




Yes:   # Aligned with opening delimiter
       foo = long_function_name(var_one, var_two,
                                var_three, var_four)

       # Aligned with opening delimiter in a dictionary
       foo = {
           long_dictionary_key: value1 +
                                value2,
           ...
       }

       # 4-space hanging indent; nothing on first line
       foo = long_function_name(
           var_one, var_two, var_three,
           var_four)

       # 4-space hanging indent in a dictionary
       foo = {
           long_dictionary_key:
               long_dictionary_value,
           ...
       }

No:    # Stuff on first line forbidden
      foo = long_function_name(var_one, var_two,
          var_three, var_four)

      # 2-space hanging indent forbidden
      foo = long_function_name(
        var_one, var_two, var_three,
        var_four)

      # No hanging indent in a dictionary
      foo = {
          long_dictionary_key:
              long_dictionary_value,
              ...
      }







空行




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


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


空格


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


括號內不要有空格.




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






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




Yes: if x == 4:
         print x, y
     x, y = y, x
No:  if x == 4 :
         print x , 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: 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)






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




Yes:
     foo = 1000  # comment
     long_name = 2  # comment that should not be aligned

     dictionary = {
         "foo": 1,
         "long_name": 2,
         }
No:
     foo       = 1000  # comment
     long_name = 2     # comment that should not be aligned

     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), 選擇合適的樣板.


函式和方法




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


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


    

  1. 外部不可見
    2. 

  2. 非常短小
    3. 

  3. 簡單明瞭
    4. 



檔案字串應該包含函式做什麼, 以及輸入和輸出的詳細描述. 通常, 不應該描述”怎麼做”, 除非是一些複雜的演演算法. 檔案字串應該提供足夠的資訊, 當別人編寫程式碼呼叫該函式時, 他不需要看一行程式碼, 只要看檔案字串就可以了. 對於複雜的程式碼, 在程式碼旁邊加註釋會比使用檔案字串更有意義.


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


    

  • Args:
    • 

  • 列出每個引數的名字, 併在名字後使用一個冒號和一個空格, 分隔對該引數的描述.如果描述太長超過了單行80字元,使用2或者4個空格的懸掛縮排(與檔案其他部分保持一致). 描述應該包括所需的型別和含義. 如果一個函式接受*foo(可變長度引數串列)或者**bar (任意關鍵字引數), 應該詳細列出*foo和**bar.
    • 

  • Returns: (或者 Yields: 用於生成器)
    • 

  • 描述傳回值的型別和語意. 如果函式傳回None, 這一部分可以省略.
    • 

  • Raises:
    • 

  • 列出與介面有關的所有異常.
    • 







def fetch_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







類




類應該在其定義下有一個用於描述該類的檔案字串. 如果你的類有公共屬性(Attributes), 那麼檔案中應該有一個屬性(Attributes)段. 並且應該遵守和函式引數相同的格式






class SampleClass(object):
    """Summary of class here.

    Longer class information....
    Longer class information....

    Attributes:
        likes_spam: A boolean indicating if we like SPAM or not.
        eggs: An integer count of the eggs we have laid.
    """

    def __init__(self, likes_spam=False):
        """Inits SampleClass with blah."""
        self.likes_spam = likes_spam
        self.eggs = 0

    def public_method(self):
        """Performs operation blah."""







塊註釋和行註釋




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


# We use a weighted dictionary search to find out where i is in
# the array.  We extrapolate position based on the largest num
# in the array and the array size and then do binary search to
# get the exact number.

if i & (i-1) == 0:        # True if i is 0 or a power of 2.


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


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


# BAD COMMENT: Now go through the b array and make sure whenever i occurs
# the next element is i+1






類




如果一個類不繼承自其它類, 就顯式的從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





 


繼承自 object 是為了使屬性(properties)正常工作, 並且這樣可以保護你的程式碼, 使其不受 PEP-3000 的一個特殊的潛在不相容性影響. 這樣做也定義了一些特殊的方法, 這些方法實現了物件的預設語意, 包括 __new__, __init__, __delattr__, __getattribute__, __setattr__, __hash__, __repr__, and __str__ .


字串




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




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)







避免在迴圈中用+和+=運運算元來累加字串. 由於字串是不可變的, 這樣做會建立不必要的臨時物件, 並且導致二次方而不是線性的執行時間. 作為替代方案, 你可以將每個子串加入串列, 然後在迴圈結束後用 .join 連線串列. (也可以將每個子串寫入一個 cStringIO.StringIO 快取中.)




Yes: items = ['']
     for last_name, first_name in employee_list:
         items.append('



 


%s, %s




‘ % (last_name, first_name))

items.append(‘‘)

employee_table = ”.join(items)

No: employee_table = ”

for last_name, first_name in employee_list:

employee_table += ‘


%s, %s’ % (last_name, first_name)

employee_table += ‘‘


 


在同一個檔案中, 保持使用字串引號的一致性. 使用單引號’或者雙引號”之一用以取用字串, 併在同一檔案中沿用. 在字串內可以使用另外一種引號, 以避免在字串中使用. GPyLint已經加入了這一檢查.


(譯者註:GPyLint疑為筆誤, 應為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.
"
           "Do it this way.
")
No:
      print """This is pretty ugly.
  Don't do this.
  """





 


 


檔案和sockets




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


除檔案外, sockets或其他類似檔案的物件在沒有必要的情況下開啟, 會有許多副作用, 例如:


    

  1. 它們可能會消耗有限的系統資源, 如檔案描述符. 如果這些資源在使用後沒有及時歸還系統, 那麼用於處理這些物件的程式碼會將資源消耗殆盡.
    2. 

  2. 持有檔案將會阻止對於檔案的其他諸如移動、刪除之類的操作.
    3. 

  3. 僅僅是從邏輯上關閉檔案和sockets, 那麼它們仍然可能會被其共享的程式在無意中進行讀或者寫操作. 只有當它們真正被關閉後, 對於它們嘗試進行讀或者寫操作將會丟擲異常, 並使得問題快速顯現出來.
    4. 





而且, 幻想當檔案物件析構時, 檔案和sockets會自動關閉, 試圖將檔案物件的生命週期和檔案的狀態系結在一起的想法, 都是不現實的. 因為有如下原因:


    

  1. 沒有任何方法可以確保執行環境會真正的執行檔案的析構. 不同的Python實現採用不同的記憶體管理技術, 比如延時垃圾處理機制. 延時垃圾處理機制可能會導致物件生命週期被任意無限制的延長.
    2. 

  2. 對於檔案意外的取用,會導致對於檔案的持有時間超出預期(比如對於異常的跟蹤, 包含有全域性變數等).
    3. 



推薦使用 “with”陳述句 以管理檔案:




with open("hello.txt") as hello_file:
    for line in hello_file:
        print line







對於不支援使用”with”陳述句的類似檔案的物件,使用 contextlib.closing():




import contextlib

with contextlib.closing(urllib.urlopen("http://www.python.org/")) as front_page:
    for line in front_page:
        print line





 


Legacy AppEngine 中Python 2.5的程式碼如使用”with”陳述句, 需要新增 “from __future__ import with_statement”.


TODO註釋


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


TODO註釋應該在所有開頭處包含”TODO”字串, 緊跟著是用括號括起來的你的名字, email地址或其它識別符號. 然後是一個可選的冒號. 接著必須有一行註釋, 解釋要做什麼. 主要目的是為了有一個統一的TODO格式, 這樣新增註釋的人就可以搜尋到(並可以按需提供更多細節). 寫了TODO註釋並不保證寫的人會親自解決問題. 當你寫了一個TODO, 請註上你的名字.




# TODO(kl@gmail.com): Use a "*" here for string repetition.
# TODO(Zeke) Change this to use relations.







如果你的TODO是”將來做某事”的形式, 那麼請確保你包含了一個指定的日期(“2009年11月解決”)或者一個特定的事件(“等到所有的客戶都可以處理XML請求就移除這些程式碼”).


匯入格式


每個匯入應該獨佔一行






Yes: import os
     import sys
No:  import os, sys







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


    

  1. 標準庫匯入
    2. 

  2. 第三方庫匯入
    3. 

  3. 應用程式指定匯入
    4. 





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




import foo
from foo import bar
from foo.bar import baz
from foo.bar import Quux
from Foob import ar




 


陳述句




通常每個陳述句應該獨佔一行


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




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中, 對於瑣碎又不太重要的訪問函式, 你應該直接使用公有變數來取代它們, 這樣可以避免額外的函式呼叫開銷. 當新增更多功能時, 你可以用屬性(property)來保持語法的一致性.


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


另一方面, 如果訪問更複雜, 或者變數的訪問開銷很顯著, 那麼你應該使用像 get_foo() 和 set_foo() 這樣的函式呼叫. 如果之前的程式碼行為允許透過屬性(property)訪問 , 那麼就不要將新的訪問函式與屬性系結. 這樣, 任何試圖透過老方法訪問變數的程式碼就沒法執行, 使用者也就會意識到複雜性發生了變化.


命名


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


 


應該避免的名稱




    

  1. 單字元名稱, 除了計數器和迭代器.
    2. 

  2. 包/模組名中的連字元(-)
    3. 

  3. 雙下劃線開頭並結尾的名稱(Python保留, 例如__init__)
    4. 





命名約定




    

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

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

  3. 用雙下劃線(__)開頭的實體變數或方法表示類內私有.
    4. 

  4. 將相關的類和頂級函式放在同一個模組裡. 不像Java, 沒必要限制一個類一個模組.
    5. 

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





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__' , 這樣當模組被匯入時主程式就不會被執行.




def main():
      ...

if __name__ == '__main__':
    main()







所有的頂級程式碼在模組匯入時都會被執行. 要小心不要去呼叫函式, 建立物件, 或者執行那些不應該在使用pydoc時執行的操作.


以上是google建議大家的Python 編碼規範。












贊(0) 




標籤：



相關推薦
 










熱門標籤
iOS (11238)微軟 (4955)Linux (4274)安全 (4180)Python (4161)效能 (3165)運維 (2774)最佳化 (2419).NET (2262)Google (2136)機器學習 (1795)併發 (1613)分散式 (1559)叢集 (1240)SQL (1174)Mysql (1060)區塊鏈 (1017)Docker (977)微服務 (922)面試 (919)Apache (743)NLP (725)Redis (719)Android (668)Git (640)架構師 (632)Nginx (630)Facebook (599)JVM (595)爬蟲 (476)
熱門文章






分享創造快樂