PEP 8 介紹

PEP8 是 Python 社群共通的風格指南，一開始是 Python 之父 Guido van Rossum 自己的撰碼風格，慢慢後來演變至今，目的在於幫助開發者寫出可讀性高且風格一致的程式。許多開源計畫，例如 Django 、 OpenStack等都是以 PEP8 為基礎再加上自己的風格建議。

程式碼編排 (Code lay-out)

這邊列出PEP8裡面的重點，有興趣可以直接看官方原文的文件會更清楚一些。

縮排 (Indentation)
每層縮排使用 4 個空格

斷行風格
正確：
# 斷行首字母與開頭的括號垂直對齊.

# 垂直縮排，首行不能有參數.

# 垂直縮排，後面還有其它代碼時，需要添加一層額外的縮排加以區別：

錯誤：
# 垂直縮排方式首行不能有引數

# 垂直縮排，首行不能有參數; 後面還有其它代碼部分時，斷行要添加一層縮進，使其與其它代碼部分能區別開來

if 條件斷行
if ( 剛好有 4 個字符，相當於一層縮排。
對於 if 條件斷行，以下幾種風格都可以：
沒有額外的縮排

添加註釋加以區分

添加額外的縮排加以區分

多行的括號

括號結束符與最後行的首字符對齊，如：

括號結束符與首行的首字符對齊, 如：

上面兩種排版的方式都可以

使用Tab還是空格縮排

用空格

每行最長長度

所有行都不超過 80 個字符

限制編輯器視窗的寬度，使能並排同時打開多個文件。
設置編輯器寬度(set width to 80)，來避免 wrapping
對於較少結構限制的長文本（如 docstrings 或註釋），行長應限制為 72 個字符。
如果團隊成員都同意使用長行，則可以將行長增加到不超過 100 個字符，但是 docstrings 和註釋還必須為 72 個字符。

有括號的長行可以用 implicit continuation 來斷行，其它的可以用 \ 來斷行，如：

操作符要和操作數在一起

# 推薦的正確的風格，這樣很容易將操作符與操作數匹配：

# 這種風格現今已不推薦使用了：

空行分隔

模組中最頂層的函數和類定義都要用兩行空行分隔
類別中的方法定義用單行分隔
要把一組相關的函數分組，可以用一些額外的空行
函數中的邏輯區塊可以加空行來分隔

原始碼的編碼

Python 核心模組文件的編碼都必須用 UTF-8（Python2 是 ASCII)。
使用默認的編碼時（Python3: UTF-8，Python2: ASCII)，不能使用編碼聲明
標準庫中，只有測試、作者名才能使用非默認的編碼，其它情況下的非 ASCII 字符用 \x, \u, \u, \N 表示法表示。

Import

每行 import 只導入一個模組：
# 正確:
import os
import sys
# 錯誤：
import sys, os
# 正確：同一模組中的內容可以在同一行導入
from subprocess import Popen, PIPE

import 語句要在文件的前面，在模組註釋及 docstrings 之後，在模組全域變數和常數定義之前。
import 分組及導入順序，每個分組之間用一行空行分隔 1. 標準庫 2. 相關第三方庫 3. 本地應用/庫的特殊導入
推薦使用絕對導入，如：
import mypkg.sibling
from mypkg import sibling
from mypkg.sibling import example

在比較覆雜的套件組成中，也可以用顯式的相對導入，如：
from . import sibling
from .sibling import example
從一個模塊中導入一個類別時，要顯示拼寫出類別名，如：
from myclass import MyClass
from foo.bar.yourclass import YourClass

如果與本地名稱衝突，可以先導入模組：
import myclass
import foo.bar.yourclass
然後使用："myclass.MyClass" 和 “foo.bar.yourclass.YourClass"。
應該避免使用 from <module> import *
模組層級的特殊名稱（如__all__)的位置：
必須在模組的 docstrings 或註釋之後，但在任何的 import 語句之前。from __future__ 比較特殊，Python 強制該語句必須在 docstrings 或註釋之後，因此風格如下：

字符引號 (String Quotes)

單引號和雙引號的功能是等同的。
對於多行字符串，應該用雙引號字符形式的三引號"""，以便與 PEP257 中的 docstrings 規範兼容

表達式和語句中的空格 (Whitespace in Expressions and Statements)

()、[]、{} 等括號內不要多餘的空格，如：
# 正確：
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
在 slice 語句中的 :實際上是一個二元操作符，因此其兩側的空格數必須相同; 但當無 slice 參數時，兩側的空格可以都省略，如：
# 以下是正確的風格：
ham[1:9], ham[1:9:3], ham[:9:3], ham[1::3], ham[1:9:]
ham[lower:upper], ham[lower:upper:], ham[lower::step]
ham[lower+offset : upper+offset]
ham[: upper_fn(x) : step_fn(x)], ham[:: step_fn(x)]
ham[lower + offset : upper + offset]
# 以下是錯誤的風格：
ham[lower + offset:upper + offset]
ham[1: 9], ham[1 :9], ham[1:9 :3]
ham[lower : : upper]
ham[ : upper]
函數調用的 () 及索引的 [] 前不要加空格，如：
# 正確風格：
spam(1)
dct[‘key’] = lst[index]
# 錯誤風格：
spam (1)
dct [‘key’] = lst [index]
不要在賦值語句中加入額外的空格來對齊，如：
# 正確的風格：
x = 1
y = 2
long_variable = 3
# 錯誤的風格:
x = 1
y = 2
long_variable = 3

其它推薦風格

任何行的行尾都不要有空白符。
在二元操作符號兩側一般都要加一個空格，一般的二元操作符號如：
賦值: =, +=, -=
比較：==, <, >, !=, <>, <=, >=, in, not in, is, is not
布林操作： and, or, not
在分優先級的表達式中，在最低優先級的操作符兩側加一個空格，但至多只能加一個空格，如：
# 正確的風格：
x = x*2 – 1
hypot2 = x*x + y*y
c = (a+b) * (a-b)
# 錯誤的風格：
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)
函數註解中的 : 前不要加空格，這符合 : 的常規風格，但是 -> 兩側要加空格，如：
# 正確的風格：
def munge(input: AnyStr): …
def munge() -> AnyStr: …
# 錯誤的風格：
def munge(input:AnyStr): …
def munge()->PosInt: …
參數註解中，如果註解的參數有默認值，指定默認值的 = 兩側要加空格，如：
# 正確的風格：
def munge(sep: AnyStr = None): …
def munge(input: AnyStr, sep: AnyStr = None, limit=1000): …
# 錯誤的風格：
def munge(input: AnyStr=None): …
def munge(input: AnyStr, limit = 1000): …

不要將多條語句組合在一行中，如：
# 正確的風格：
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/for/while 區塊內的程式碼很少，組合在一行有時還是可以接受的
# 但是不推薦，如：
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()

註解 (Comments)

註解內容必須要和程式碼相關！
註解應該是完整的語句，首字母一般大寫(英文)，一般要有句號。
註解很短時句號可以省略。
區塊註解一般由多個段落組成。用英文寫註解

區塊註解 (Block Comments)

每行用 # 及一個空格開始，如 #
段落用一個只有 # 的行分隔

行內註解 (Inline Comments)

註解與語句內容至少用兩個空格分開，註解用 # 加一個空格開始
# 不要像下面這樣，註解內容沒有必要
x = x + 1 # Increment x
# 但是有時，如下面的註解會很有用
x = x + 1 # Compensate for border

文件字串 (Documentation Strings)

公開的模組、函數、類及方法都應該有文件字串，而非公開的方法可以用註解來代替，且註解放置在 def 行之後。
多行的文件字串，結束符號要自成一行，如：

單行的文件字串，結束符號和內容放在同一行

命名 (Naming Conventions)

沒有推薦的風格，但是別人要能從你的程式碼中看出你用的是什麽風格，常用的風格如下：

• b 單個小寫字母

• B 單個大寫字母

• lowercase

• lower_case_with_underscores

• UPPERCASE

• UPPER_CASE_WITH_UNDERSCORES

• CapitalizedWords, 這種風格中，對於縮寫詞應全部用大寫，如

• HTTPServerError 比 HttpServerError 好

• mixedCase
  Capitalized_Words_With_Underscores，這個太醜，不要用這種！

• st_mode、st_mtime 等前綴，一般是系統接口返回，如果自己寫的程式碼不推薦用這種

• _single_leading_underscore : 弱 “內部使用” 指示器，這種對象用 from M import * 不會被導入

• single_trailing_underscore_ : 可以用來和 Python 關鍵詞進行區分，如 Tkinter.Toplevel(master, class_=’ClassName’)

• __double_leading_underscore : 命名一個類屬性時，可以進行命名矯正，例如 class FooBar 內的 __boo 會變成 _FooBar__boo

• double_leading_and_trailing_underscore : “magic” 對象，不要自己發明這種對象

命名習慣 (Prescriptive: Naming Conventions)

• 不用單個 l, O, I 等這樣的單個字符來命名，它們與數字1,0不好區分

• 套件名和模組名：全部用小寫，必要時可用 _，但不推薦，C/C++ 的擴展模組，如果其對應有 Python 版本，那麽 C/C++ 擴展模組名前加 _

• 類別名：用 CapWords 風格

• 異常名：用 CapWords 風格，一般應該有 Error 後綴

• 全域變數名：能用 from M import * 導入的變數全部放在 __all__ 中，或者全域變數用 _ 做前綴

• 函數名：應該用全部用小寫，單詞間可以用 _ 分隔，如 my_func，不推薦用 mixedCase 風格

• 函數和方法的參數：實例方法的第一個參數用 self, 類別方法的第一個參數用 cls，如果參數與關鍵字衝突，在參數名後加 _ 後綴，如 class_

• 實例變數和方法： 用小寫字符和 _, 非公開的實例變數和方法用一個 _ 做前綴; 避免與子類別中的名字衝突，類的變數可用兩個 _ 作前綴，例如 class FooBar 內的 __boo 會變成只能通過 FooBar._FooBar__boo 讀取

• 常數：全部大寫，可用 _ 分隔，如 MAX_OVERFLOW、TOTAL

推薦的程式撰寫方式 (Programming Recommendations)

字符串連接不要用 a += b 或者 a = a + b, 用 “.join(), 後者性能更好。跟 None 的比較用 is 和 is not，不要用 ==，如果你想判斷 if x is not None, 不要縮寫成 if x 使用 if foo is not None，而不是 if not foo is None，前者更加易讀

如果要實現序列比較操作的話，應將 6 個操作（__eq__ , __ne__ , __lt__ , __le__ , __gt__ , __ge__）全部實現，可以借助 functools.total_ordering() 修飾器來減少工作量

將函數保存在一個變數中應該用 def f(x): return 2*x， 而非 f = lambda x: 2*x，後者不利於調試

自定義的異常類應該繼承至 Exception 類，而非 BaseException 類。Python 2 中拋出異常用 raise ValueError(‘message’)，而非 raise ValueRoor, ‘message’

盡量可以的指明異常名，如：

避免使用無異常名的 except: 語句，它會捕獲全部的異常（如 Ctrl C）。
將異常綁定到名字的方法：

try: 中的語句要盡量減少，如：
# 正確的寫法：

# 錯誤的寫法

如果資源只適用於某個代碼段內，使用 with 或 try/finally 來確保能進行清理工作
上下文管理器應用通過一個單獨的函數或方法來呼叫，如：
# 正確的做法：

# 錯誤的做法：

return 語句應該一致，如：
# 正確的做法：

# 錯誤的做法：

使用字符串的方法，而不是用 string 模組中的方法
使用 “.startswith() 和 “.endswidth() 而不用 slicing 來檢查前綴和後綴：
# 正確：
if foo.startswith(‘bar’):
# 錯誤：
if foo[:3] == ‘bar’:
判斷對象的類型用 isinstance 而不直接 type 比較，如：
# 正確：
if isinstance(obj, int):
# 錯誤:
if type(obj) is type(1):
對序列是否空的判斷不用 len，如：
# 正確：
if not seq:
if seq:
# 錯誤：
if len(seq):
if not len(seq):
布林值的比較：
# 正確：
if greeting:
# 不要這樣:
if greeting == True:
# 這樣更不行：
if greeting is True: