Python 程式碼風格指引

簡介

本文件提供 Python 主要發行版本標準程式庫中的 Python 程式碼所用的撰寫慣例。關於 Python 的 C 實作中所用的 C 語言風格指引，請參考相關的 PEP[1]。

本文件改寫自 Guido 所寫的 Python 風格指引文章[2]，並增添一些 Barry 的風格指引[5]的內容。當兩者有衝突時，本 PEP 以 Guido 風格為準。本 PEP 可能仍未完成（事實上，可能永遠不會完工 <眨眼>）。

愚蠢的一致性是小心眼中的妖怪

Guido 的重要見解之一是：程式碼被閱讀的次數，遠大於被撰寫的次數。提供本指引的目的，是為了增進程式碼的可讀性，並使 Python 程式碼在各方面保持一致性。如同 PEP 20 [6] 所說的「可讀性至關重要」。

風格指引關注的是一致性。和本指引一致很重要，在專案中保持一致性又更重要，但在 module 或 function 中保持一致性則最重要。

但更更重要的是：知道何時該不一致 －－ 有時候風格指引就是無法適用。有疑惑時，運用你的最佳判斷力。看看其他例子，並決定何者最好看。需要的時候，儘管發問。

打破特定規則的兩個好理由：

1. 使用該規則會造成程式碼可讀性變差，特別是對習慣該規則的人來說，可讀性也變差的時候。
2. 為了和前後（可能是因為歷史性因素）打破該規則的程式碼保持一致性時 －－ 雖然這也是清理他人雜亂程式碼的時機（在真正的 Extreme Programming 開發中）。

程式碼編排

class Rectangle(Blob):
 
    def __init__(self, width, height,
                 color='black', emphasis=None, highlight=0):
        if width == 0 and height == 0 and \
           color == 'red' and emphasis == 'strong' or \
           highlight > 100:
            raise ValueError("sorry, you lose")
        if width == 0 and height == 0 and (color == 'red' or
                                           emphasis is None):
            raise ValueError("I don't think so")
        Blob.__init__(self, width, height,
                      color, emphasis, highlight)

import

import 通常應該分成不同行，例如：

這樣寫：

import os
import sys

不要寫：

import sys, os

但這種情況是可以的：

from subprocess import Popen, PIPE

import 應該永遠放在檔案頂端，也就是在 module 的註解和 docstring 之後，而在 module 的全域變數和常數之前。

import 應該以以下順序分組：

1. 標準程式庫的 import
2. 相關第三方程式庫的 import
3. 己方應用程式/程式庫特定的 import

每組 import 之間應該以一個空白行分隔。 將任何相關的 __all__ 細述放在 import 之下。

極不鼓勵在 package 之間使用相對 import。

所有 import 都要永遠用 package 的絕對路徑。雖然現在 PEP 328 [7] 已經在 Python 2.5 中完全實作，但它明確表明相對 import 的方式仍不鼓勵使用；絕對 import 更有可攜性，通常也更有可讀性。

從含有 class 定義的 module 中 import class 時，這樣寫通常是可以的

from myclass import MyClass
from foo.bar.yourclass import YourClass

如果會造成命名衝突，可以改成

import myclass
import foo.bar.yourclass

然後使用 "myclass.MyClass" 和 "foo.bar.yourclass.YourClass"

expression 和 statement 中的空白

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

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

if x == 4: print x, y; x, y = y, x

if x == 4 : print x , y ; x , y = y , x

spam(1)

spam (1)

dict['key'] = list[index]

dict ['key'] = list [index]

x = 1
y = 2
long_variable = 3

x             = 1
y             = 2
long_variable = 3

i = i + 1
submitted += 1
x = x * 2 - 1
hypot2 = x * x + y * y
c = (a + b) * (a - b)

i=i+1
submitted +=1
x = x*2 - 1
hypot2 = x*x + y*y
c = (a+b) * (a-b)

def complex(real, imag=0.0):
    return magic(r=real, i=imag)

def complex(real, imag = 0.0):
    return magic(r = real, i = imag)

if foo == 'blah':
    do_blah_thing()
do_one()
do_two()
do_three()

if foo == 'blah': do_blah_thing()
do_one(); do_two(); do_three()

if foo == 'blah': do_blah_thing()
for x in lst: total += x
while t < 10: t = delay()

if foo == 'blah': do_blah_thing()
else: do_non_blah_thing()

try: something()
finally: cleanup()
 
do_one(); do_two(); do_three(long, argument,
                             list, like, this)
 
if foo == 'blah': one(); two(); three()

註解

註解和程式碼牴觸比沒有註解還糟。更改程式碼之後，永遠將更新註解列為優先事項。

註解應該是完整的句子。當註解是片語或句子時，第一個單字應該大寫，除非它是一個小寫開頭的識別字（絕對不要改變識別字的大小寫！）。

如果註解很短，結尾的句點可以省略。區塊註解通常包含由完整句子組成的一或多個段落，其中每個句子都該以句點作結尾。

每個句子的句點後應該加兩個空白。

寫英文時，Strunk 和 White 的 "The Elements of Style" 值得參考。

非英語系國家的 Python 程式設計師：請用英文寫註解，除非 120% 確定不會有不懂你語言的人閱讀你的程式碼。

x = x + 1                 # Increment x

x = x + 1                 # Compensate for border

文件字串

好的文件字串（即 docstring）撰寫慣例載於 PEP 257 [3]。

所有 public 的 module、function、class、method 都該寫文件字串。非 public 的 method 不需要寫文件字串，但應該用註解描述該 method 的作用。這註解應該放在 "def" 行之下。

PEP 257 敘述了好的文件字串慣例。注意最重要的是，多行文件字串結尾的 """ 應該自己獨立一行，而且前面最好加一個空白行，例如：

"""Return a foobang
Optional plotz says to frobnicate the bizbaz first.
"""

對於只有一行的 docstring，結尾的 """ 可以放在同一行。 

版本紀錄

如果需要在原始檔中加進 Subversion、CVS 或 RCS 的資料，可以這樣做：

__version__ = "$Revision: 60919 $"
# $Source$

這幾行應該放在 module 的 docstring 之下，而在其他程式碼之前，並在上下各以一個空白行分隔。（譯註：Subversion 的話，第二行應該可以改用 "# $Id$"）

命名慣例

Python 程式庫的命名慣例有點混亂，所以不太可能讓它完全一致 －－ 不過這裡提供的是目前建議的命名標準。新的 module 和 package（包括第三方 framework）都應該依此標準撰寫，不過當現存的程式庫用的是不同風格時，保持內部的一致性比較重要。

Tkinter.Toplevel(master, class_='ClassName')

程式撰寫建議

程式應該以不會在特定 Python 實作（PyPy, Jython, IronPython, Pyrex, Psyco 之類）上不利的方式撰寫。

舉例來說，不要依賴 CPython 對像 a+=b 或 a=a+b 這類形式的 statement 的高效能就地字串串接實作。這些 statement 在 Jython 中執行比較慢。在程式庫效能要求高的部分，應該使用 ''.join() 形式。這樣可以確保串接在各種實作中，都只耗費線性時間。

和像 None 這樣的 singleton 比較時，應該永遠使用 'is' 或 'is not'，絕對不要用相等運算子。

也要注意寫了 "if x" 但其實是想表達 "if x is not None" 的情況 －－ 例如，測試預設值是 None 的變數或參數是否設了新值時。新值可能是在邏輯判斷中有機會被當作 false 的型別（例如容器）！

使用 class 型 exception

字串型 exception 在新程式碼中禁止使用，因為這功能將在 Python 2.6 移除。 module 和 package 應該定義它們自己特定的基礎 exception class，這些 class 應該是內建 Exception class 的 subclass。永遠寫上 class 的文件字串。例如：

class MessageError(Exception):
    """Base class for errors in the email package."""

class 命名慣例適用於此，只是如果 exception 是代表錯誤時，exception class 名稱字尾要加上 'Error'。非錯誤類的 exception 不需要加特定字尾。

發出 exception 時，寫成 "raise ValueError('message')" 而不要用舊格式 "raise ValueError, 'message'"。

推薦括號格式是因為，exception 參數很長或包含格式化字串時，由於有括號，可以不必用行接續字元。舊的格式將在 Python 3000 （譯註：3.0）中移除。

捕捉 exception 時，盡可能註明特定的 exception 而不要只用空的 'except:' 子句。

例如： 

try:
    import platform_specific_module
except ImportError:
    platform_specific_module = None

空的 'except:' 子句會捕捉 SystemExit 和 KeyboardInterrupt 這兩個 exception，造成 Control-C 無法中止程式，而且可能掩蓋住其他問題。如果想捕捉所有代表程式錯誤的 exception，可以用 'except Exception:'。

有個好的法則是限制空的 'except' 子句只能用在兩種情況：

1. exception 會被印出或記錄，至少使用者能注意到有錯誤發生。
2. 程式需要做些清理工作，但之後就用 'raise' 將 exception 往上發。'try ...finally' 是處理此情況較好的方式。

此外，對於所有 try/except 子句，將 'try' 子句的程式碼數量限制在所需的最少數量。如此也能避免掩飾住 bug。

這麼寫：

try:
    value = collection[key]
except KeyError:
    return key_not_found(key)
else:
    return handle_value(value)

不要寫：

try:
    # Too broad! （太廣！）
    return handle_value(collection[key])
except KeyError:
    # Will also catch KeyError raised by handle_value()
    # （也會捕捉到 handle_value() 發出的 KeyError）
    return key_not_found(key)

用字串的 method 而不要用 string module 的 function。

字串的 method 總是快得多，而且和 unicode 字串共用同樣的 API。需要相容於比 Python 2.0 舊的版本時，可以打破此規則。

用 ''.startswith() 和 ''.endswith() 比對字串的字首和字尾，而不要用字串 slice。

startswith() 和 endswith() 更清楚明白且不容易出錯。例如：
這麼寫：

if foo.startswith('bar'):

不要寫：

if foo[:3] == 'bar':

唯一例外是你的程式碼必須在 Python 1.5.2 運行（希望不要）。

比較物件型別應該永遠用 isinstance() 而不要直接比較型別。

這麼寫：

if isinstance(obj, int):

不要寫：

if type(obj) is type(1):

檢查物件是不是字串的時候，別忘了它也可能是 unicode 字串！Python 2.3 中，str 和 unicode 有共同的 base class －－ basestring，所以可以這樣寫：

if isinstance(obj, basestring):

Python 2.2 中，types module 裡為此用途定義了 StringTypes 型別：

from types import StringTypes
if isinstance(obj, StringTypes):

Python 2.0 和 2.1 中，應該這麼寫：

from types import StringType, UnicodeType
if isinstance(obj, StringType) or \
   isinstance(obj, UnicodeType) :

對於序列（string, list, tuple），利用空序列代表 false 的特性

這麼寫：

if not seq:
if seq:

不要寫：

if len(seq)
if not len(seq)

不要寫出尾端需要有大量空白的字串常量。這些尾端的空白視覺上不易辨別，而且有些編輯器（或者像是 reindent.py）會將它們刪除。

不要將邏輯值用 == 去和 True 或 False 比較

這麼寫：

if greeting:

不要寫：

if greeting == True:

更不要：

if greeting is True:

References

1. PEP 7, Style Guide for C Code, van Rossum
2. http://www.python.org/doc/essays/styleguide.html
3. PEP 257, Docstring Conventions, Goodger, van Rossum
4. http://www.wikipedia.com/wiki/CamelCase
5. Barry's GNU Mailman style guide http://barry.warsaw.us/software/STYLEGUIDE.txt
6. PEP 20, The Zen of Python
7. PEP 328, Imports: Multi-Line and Absolute/Relative