關(guān)鍵時(shí)刻，第一時(shí)間送達(dá)！

作者：Jasmine Finer

編譯：wLsq

推薦導(dǎo)讀：Python的初學(xué)者，開發(fā)者都應(yīng)該知道的代碼可讀性提高技巧，本篇主要介紹了如下內(nèi)容：

PEP 8是什么以及它存在的原因

為什么你應(yīng)該編寫符合PEP 8標(biāo)準(zhǔn)的代碼

如何編寫符合PEP 8的代碼

▍為什么我們需要PEP 8?

PEP 8的存在是為了提高Python代碼的可讀性的。但為什么可讀性如此重要？為什么編寫可讀代碼是Python語言的指導(dǎo)原則之一？

正如Guido van Rossum所說：“代碼的閱讀頻率遠(yuǎn)高于編寫代碼的頻率”。比如，你可能花費(fèi)幾分鐘或一整天的時(shí)間編寫一段代碼。一旦你寫完它，你可能就再也不會(huì)寫了，但你肯定要再讀一遍。或者，這段代碼可能仍然是你正在進(jìn)行的項(xiàng)目的一部分。每次回到該文件時(shí)，你都必須記住該代碼的作用以及編寫代碼的原因，因此可讀性非常重要。

如果你是Python的新手，可能很難記住幾天或幾周之前編寫代碼的作用。但如果你遵循PEP 8，你就很好地命名了你的變量，添加了足夠的空格更容易遵循代碼中的邏輯步驟，還可以很好地注釋你的代碼。所有這些都意味著你的代碼更易讀。

如果你正在尋找開發(fā)工作，那么遵循PEP 8尤為重要。編寫清晰易讀的代碼顯示出專業(yè)性。它會(huì)告訴你的老板你知道如何很好地構(gòu)建代碼。

如果你有更多編寫Python代碼的經(jīng)驗(yàn)，那么你可能需要與其他人協(xié)作。其他人可能從未見過你或以前見過你的編碼風(fēng)格，必須閱讀并理解你的代碼。

▍命名的規(guī)定

編寫Python代碼時(shí)，必須列舉很多東西：變量，函數(shù)，類，包等。選擇合理的名字將為你節(jié)省很多時(shí)間和精力。你將能夠從名稱中讀懂某個(gè)變量，函數(shù)或類所代表的含義。你還可以避免使用那些可能導(dǎo)致后期難以調(diào)試錯(cuò)誤的不適當(dāng)?shù)拿Q。

命名樣式

下表總結(jié)了Python代碼中的一些常見類型和命名規(guī)則：

為了編寫可讀代碼，你仍然需要謹(jǐn)慎選擇字母和單詞。除了在代碼中選擇正確的命名樣式外，還必須仔細(xì)選擇名稱。

如何選擇名稱

在編寫代碼時(shí)，你應(yīng)該在命名選擇中加入相當(dāng)多的思考，因?yàn)檫@樣可以使代碼更具可讀性。在Python中命名對(duì)象的最佳方法是使用描述性名稱來清楚表明對(duì)象所代表的內(nèi)容。

命名變量時(shí)，你可能會(huì)選擇簡單的單字母小寫名稱，例如x。但是，除非你使用x作為數(shù)學(xué)函數(shù)的參數(shù)，否則不清楚x代表什么。想象一下，你將一個(gè)人的姓名存儲(chǔ)為字符串，并且你希望使用字符串切片來格式化其名稱。你最終會(huì)得到這樣的東西：

這是有效的，但你必須跟蹤x，y和z代表的內(nèi)容。這可能讓其他人產(chǎn)生困惑，更明確的名稱選擇將是這樣的：

同樣，為了減少你所做的輸入量，在選擇名稱時(shí)使用縮寫是很有幫助的。在下面的例子中，我們定義了一個(gè)函數(shù)db()，它接受一個(gè)參數(shù)x并將其加倍：

乍一看，這似乎是一個(gè)明智的選擇。 db()很容易成為double的縮寫。但想象一下，幾天后回到這段代碼，你可能已經(jīng)忘記了你試圖通過這個(gè)功能實(shí)現(xiàn)的目標(biāo)，這會(huì)花很長時(shí)間回想。

以下示例更加清晰。如果你在編寫代碼后幾天回到此代碼，你仍然可以閱讀并理解此函數(shù)的用途：

同樣的理念適用于Python中的所有其他數(shù)據(jù)類型和對(duì)象，要始終盡量使用最簡潔但最具描述性的名稱。

▍代碼布局

如何布置代碼對(duì)于它的可讀性有很大的作用。此處，你將學(xué)習(xí)如何添加垂直空格以提高代碼的可讀性，以及如何處理PEP 8中建議的79字符行限制。

空白行

垂直空白或空行可以極大地提高代碼的可讀性。聚集在一起的代碼可能是壓倒性的，難以閱讀。同樣，代碼中的空行太多會(huì)使其看起來非常稀疏，讀者可能需要滾動(dòng)超過必要的行。以下是關(guān)于如何使用垂直空白的三個(gè)關(guān)鍵指南。

1.最外層函數(shù)和類之間要留有兩個(gè)空行。最高層函數(shù)和類應(yīng)該是自包含的，并處理單獨(dú)的功能。在它們周圍放置額外的垂直空間是有意義的，因此很明顯它們是分開的：

2.一個(gè)類里面的方法之間用一個(gè)空行。在一個(gè)類中，方法都彼此相關(guān)。最好只在它們之間留一行：

3.在函數(shù)內(nèi)使用空白行以顯示清晰的步驟。有時(shí)，復(fù)雜的函數(shù)必須在return語句之前完成幾個(gè)步驟。為了幫助讀者理解函數(shù)內(nèi)部的邏輯，在每個(gè)步驟之間留一個(gè)空行會(huì)很有幫助。

在下面的示例中，有一個(gè)計(jì)算列表方差的函數(shù)。這是兩步問題，所以我在每個(gè)步驟之間留下了一個(gè)空行。在return語句之前還有一個(gè)空行。這有助于讀者清楚地看到返回的內(nèi)容：

如果仔細(xì)使用垂直空白，可以大大提高代碼的可讀性。它有助于讀者直觀地理解你的代碼如何分成幾個(gè)部分，以及這些部分如何相互關(guān)聯(lián)。

最大行長度和換行

PEP 8建議行數(shù)限制為79個(gè)字符。當(dāng)然，將語句保持在79個(gè)字符以內(nèi)并不總是可行的。 PEP 8給出了允許語句在多行上運(yùn)行的方法。

如果代碼包含在括號(hào)，方括號(hào)或大括號(hào)中，Python將假定行繼續(xù)：

如果不能使用按規(guī)則繼續(xù)，那么你可以使用反斜杠來代替換行：

如果需要在二元運(yùn)算符周圍換行，例如 + 和 *，則它應(yīng)該在運(yùn)算符之前發(fā)生。數(shù)學(xué)家認(rèn)為在二元運(yùn)算符之前換行可提高可讀性。比較以下兩個(gè)例子。

下面是在二元運(yùn)算符之前換行的示例：

你可以立刻看到正在添加或減去的變量，因?yàn)椴僮鞣o挨著正在操作的變量。 現(xiàn)在，讓我們看一個(gè)在二元運(yùn)算符之后換行的示例：

在這里，很難看出哪個(gè)變量被添加，哪個(gè)變量被減去。

▍縮進(jìn)

縮進(jìn)或前導(dǎo)空格在Python中非常重要。Python中代碼行的縮進(jìn)級(jí)別決定了語句如何組合在一起。請(qǐng)看以下示例：

縮進(jìn)的print語句讓Python知道只有if語句返回True才能執(zhí)行它。相同的縮進(jìn)會(huì)告訴Python在調(diào)用函數(shù)或代碼屬于給定類時(shí)要執(zhí)行的代碼。PEP 8給出的關(guān)鍵縮進(jìn)規(guī)則如下：

使用4個(gè)連續(xù)的空格來表示縮進(jìn)；

首選使用空格，再使用Tab；

Tab鍵與空格

如上所述，在縮進(jìn)代碼時(shí)應(yīng)首先使用空格而不是Tab鍵。你可以在文本編輯器中調(diào)整Tab設(shè)置：當(dāng)你按Tab鍵時(shí)，輸出4個(gè)空格而不是Tab符號(hào)。

如果你使用的是Python 2,并且混合使用了Tab和空格來縮進(jìn)代碼，那么在運(yùn)行它時(shí)將不會(huì)看到錯(cuò)誤。為了幫助你檢查一致性，可以在從命令行運(yùn)行Python 2代碼時(shí)添加 -t 標(biāo)志。當(dāng)你使用的Tab和空格不一致時(shí)，解釋程序?qū)l(fā)出警告：

如果使用 -tt 標(biāo)志，則解釋器將發(fā)出錯(cuò)誤而不是警告，并且你的代碼將不會(huì)運(yùn)行。使用此方法的好處是解釋器會(huì)告訴你不一致的位置：

Python 3不允許混合Tab和空格。因此，如果你使用的是Python 3，則會(huì)自動(dòng)發(fā)出以下錯(cuò)誤：

你可以使用Tab或空格來編寫Python代碼，以表示縮進(jìn)。但是，如果你使用的是Python 3，則必須與你的選擇保持一致。否則，代碼將無法運(yùn)行。PEP 8建議始終使用4個(gè)連續(xù)空格來表示縮進(jìn)。

換行后的縮進(jìn)

當(dāng)使用換行將行保持在79個(gè)字符以下時(shí)，使用縮進(jìn)來提高可讀性是很有用的。它允許讀者區(qū)分兩行代碼和跨越兩行的單行代碼。你可以使用兩種縮進(jìn)樣式。

第一個(gè)是將縮進(jìn)塊與開口分隔符對(duì)齊：

有時(shí)你會(huì)發(fā)現(xiàn)只需要4個(gè)空格就可以與開口分隔符對(duì)齊。這通常發(fā)生在跨越多行的if語句中，因?yàn)閕f，space和opening括號(hào)恰巧組成4個(gè)字符。在這種情況下，可能很難確定if語句中嵌套代碼塊的開始位置：

在這種情況下，PEP 8提供了兩種替代方案來幫助提高可讀性：

1. 在條件之后添加注釋

2. 在換行中添加額外的縮進(jìn)

第二個(gè)換行符后縮進(jìn)方式是懸掛縮進(jìn)：

這意味著除了段落或語句中的第一行之外的每一行都是縮進(jìn)的。你可以使用懸掛縮進(jìn)來直觀地表示代碼行延續(xù)。下面一個(gè)例子：

使用懸掛縮進(jìn)時(shí)，添加額外的縮進(jìn)以區(qū)分連續(xù)行與函數(shù)內(nèi)包含的代碼。以下示例很難閱讀，因?yàn)楹瘮?shù)內(nèi)部的代碼與連續(xù)行的縮進(jìn)級(jí)別相同：

因此，最好在下一行使用雙縮進(jìn)。這有助于區(qū)分函數(shù)參數(shù)和函數(shù)體，從而提高可讀性：

總結(jié)一下，換行后縮進(jìn)有兩種方法，第一種是將縮進(jìn)塊與開口分隔符對(duì)齊，第二種是使用懸掛縮進(jìn)。你可以自由選擇在換行符后使用哪種縮進(jìn)方法。

在哪里放置右括號(hào)

換行允許你斷開括號(hào)，方括號(hào)或大括號(hào)內(nèi)的行。PEP 8為右中括號(hào)的位置提供了兩個(gè)選項(xiàng)：

1. 使用前一行的第一個(gè)非空白字符排列右括號(hào)：

2. 將右括號(hào)與構(gòu)造開始行的第一個(gè)字符對(duì)齊：

可以自由選擇使用的選項(xiàng)，但一致性是關(guān)鍵，所以盡量堅(jiān)持上述方法之一。

▍注釋

注釋代碼非常重要，這樣你和任何協(xié)作者都可以理解它。當(dāng)你或其他人閱讀評(píng)論時(shí)，他們應(yīng)該能夠輕松理解注釋所對(duì)應(yīng)的代碼以及它與其余代碼的匹配程度。

以下是在為代碼添加注釋時(shí)要記住的一些要點(diǎn)：

將注釋和文檔字符串的行長限制為72個(gè)字符；

使用完整的句子，以大寫字母開頭；

如果更改代碼，請(qǐng)務(wù)必更新注釋；

塊注釋

使用塊注釋來標(biāo)注一小部分代碼。當(dāng)你必須編寫多行代碼來執(zhí)行單個(gè)操作（例如從文件導(dǎo)入數(shù)據(jù)或更新數(shù)據(jù)庫條目）時(shí)，它們非常有用。它們很重要，因?yàn)樗鼈兛梢詭椭渌死斫饨o定代碼塊的用途和功能。

PEP 8為編寫塊注釋提供了以下規(guī)則：

將塊注釋縮進(jìn)到與它們描述的代碼相同的級(jí)別；

＃后面加單個(gè)空格后開始注釋；

用包含單個(gè)＃的行分隔段落；

這是一個(gè)解釋for循環(huán)功能的塊注釋。請(qǐng)注意，句子換行到新行以保留79個(gè)字符行限制：

有時(shí)，如果代碼是非常技術(shù)性的，那么有必要在塊注釋中使用多個(gè)段落：

如果你對(duì)使用哪種注釋類型更適合存在疑問，那么塊注釋通常是可行的方法。盡可能在整個(gè)代碼中使用它們，但如果你對(duì)代碼進(jìn)行了更改，也請(qǐng)務(wù)必更新它們。

行注釋

行注釋解釋了一段代碼中的單個(gè)語句。它們有助于提醒你，或向其他人解釋為什么需要某行代碼。以下是PEP 8對(duì)它們的建議：

與代碼寫在同一行；

使用兩個(gè)或多個(gè)空格將代碼與行注釋分開；

＃后加單個(gè)空格，然后進(jìn)行行注釋；

不要用它們來解釋已經(jīng)很明顯的問題；

以下是行注釋的示例：

有時(shí)，行注釋似乎是必要的，但你可以使用更好的命名規(guī)則。比如，這是一個(gè)例子：

這里，行注釋確實(shí)提供了額外的信息。但是，使用x作為人名的變量名是不好的做法。如果重命名變量，則無需行注釋：

最后，像這樣的行注釋是不好的做法，因?yàn)樗鼈冏⑨屃嗣黠@且混亂的代碼：

行注釋比塊注釋更具體，但很容易在不需要時(shí)添加它們，這會(huì)導(dǎo)致混亂，而你可以總是使用塊注釋，而不必?fù)?dān)心這些。因此，除非確定需要使用行注釋，否則更多使用塊注釋，則代碼更可能符合PEP 8。

文檔字符串

文檔字符串是用雙（''''''）或單引號(hào)（''''''）括起來的字符串，它們出現(xiàn)在任何函數(shù)，類，方法或模塊的第一行。你可以使用它們來解釋和記錄一個(gè)特定的代碼塊。

適用于文檔字符串的最重要規(guī)則如下：

環(huán)繞文檔字符串，兩邊都有三個(gè)雙引號(hào)，如 '''''' 這是一個(gè)文檔字符串 ''''''；

為所有公共模塊，函數(shù)，類和方法編寫它們；

將單行結(jié)束多行文檔字符串的 '''''' 放在一行上：

對(duì)于單行文檔字符串，請(qǐng)將 '''''' 保留在同一行：

▍表達(dá)式和語句的空格

空格在表達(dá)式和語句中正確使用時(shí)非常有用。如果沒有足夠的空白，那么代碼可能難以閱讀，因?yàn)樗鼈兌季奂谝黄?。如果空白太多，那么在語句中可能難以在視覺上組合相關(guān)術(shù)語。

二元運(yùn)算符兩邊的空白

以下二元運(yùn)算符兩邊都有一個(gè)空格：

賦值運(yùn)算符（=，+=， -=）

比較運(yùn)算符（==，=！，>，=，

布爾運(yùn)算法（and，not，or）

如果語句中有多個(gè)運(yùn)算符，則在每個(gè)運(yùn)算符之前和之后添加單個(gè)空格可能會(huì)讓人感到困惑。相反，最好只在優(yōu)先級(jí)最低的運(yùn)算符兩邊添加空格，尤其是在執(zhí)行數(shù)學(xué)運(yùn)算時(shí)。以下是幾個(gè)例子：

你還可以將此應(yīng)用于有多個(gè)條件的if語句：

在上面的示例中，and 運(yùn)算符具有最低優(yōu)先級(jí)。因此，可以更清楚地表達(dá)if語句如下：

你可以自由選擇哪個(gè)更清晰，但需要注意的是必須在運(yùn)算符的任何一側(cè)使用相同數(shù)量的空格。以下是不可接受的：

在切片中，冒號(hào)充當(dāng)二元運(yùn)算符。因此，上面所說的規(guī)則同樣適用，任何一方都應(yīng)該有相同數(shù)量的空白。以下列表切片示例：

何時(shí)避免添加空格

在某些情況下，添加空格會(huì)使代碼更難以閱讀。太多的空格會(huì)使代碼過于稀疏而難以理解。PEP 8總結(jié)了空白不合適的非常明顯的例子。

避免添加空格的最重要的地方是在一行的末尾，這稱為尾部空格。它是不容易察覺的，可能產(chǎn)生難以追蹤的錯(cuò)誤。

以下總結(jié)了一些應(yīng)避免添加空格的情況：

緊靠括號(hào)，括號(hào)或大括號(hào)內(nèi)：

在逗號(hào)，分號(hào)或冒號(hào)之前：

在打開函數(shù)調(diào)用的參數(shù)列表的開括號(hào)之前：

在開始索引或切片的開括號(hào)之前：

在末尾逗號(hào)和右括號(hào)之間：

要對(duì)齊賦值運(yùn)算符：

確保代碼中的任何位置都沒有尾部空格。在其他情況下，PEP 8不鼓勵(lì)添加額外的空格，例如立即在括號(hào)內(nèi)，以及逗號(hào)和冒號(hào)之前。你也應(yīng)該永遠(yuǎn)不要添加額外的空格為了對(duì)齊運(yùn)算符。

▍編程建議

你經(jīng)常會(huì)發(fā)現(xiàn)有幾種方法可以在Python中執(zhí)行相同的操作（以及任何其他編程語言）。下面你將看到PEP 8提供的一些建議，以消除這種歧義并保持一致性。

1. 不要使用等價(jià)運(yùn)算符==將布爾值與True或False進(jìn)行比較。你經(jīng)常需要檢查布爾值是True還是False。

這里不需要使用等價(jià)運(yùn)算符==，bool只能取值True或False，因此寫下面的內(nèi)容就足夠了，這種使用布爾值執(zhí)行if語句的方法需要更少的代碼并且更簡單。

2. 在if語句中直接判斷空序列是否為假。如果要檢查列表是否為空，則可能需要檢查列表的長度。如果列表為空，則其長度為0，在if語句中使用時(shí)等于False。這是一個(gè)例子：

但是，在Python中，任何空列表，字符串或元組都是假的。因此，我們可以給出一個(gè)更簡單的替代方案：

雖然兩個(gè)例子都打印出來了，第二個(gè)選項(xiàng)更簡單，所以PEP 8鼓勵(lì)使用它。

3.在if語句中使用 is not 而非 not...is。如果你要檢查變量是否具有已定義的值，則有兩個(gè)選項(xiàng)。第一個(gè)是使用 x is not None，如下例所示：

第二種選擇是 x is None，然后根據(jù) not 結(jié)果得到if語句：

雖然兩個(gè)選項(xiàng)都將被正確評(píng)估，但第一個(gè)選項(xiàng)更簡單。

4. 當(dāng)你的意思是x is not None 的時(shí)候，不要使用if x。有時(shí)，你可能擁有一個(gè)默認(rèn)情況下參數(shù)為None的函數(shù)。檢查這樣的參數(shù)arg是否被賦予不同值時(shí)常見的錯(cuò)誤是使用以下內(nèi)容：

此代碼檢查arg是否為真。相反，你要檢查arg是否為None，因此最好使用以下內(nèi)容：

這里犯的錯(cuò)誤是假設(shè)了 not None和 truthy 是等價(jià)的。你可以設(shè)置arg = []。如上所述，空列表在Python中被評(píng)估為假的。因此，即使已經(jīng)分配了參數(shù)arg，也不滿足條件，因此不會(huì)執(zhí)行if語句主體中的代碼。

5. 使用.startswith()和.endswith()而不是切片。如果你嘗試檢查字符串單詞是否帶有前綴或帶有后綴的單詞cat，那么使用列表切片似乎是明智的。但是，列表切片容易出錯(cuò)，你必須對(duì)前綴或后綴中的字符數(shù)進(jìn)行硬編碼。對(duì)于那些不太熟悉Python列表切片的人來說，你還想要實(shí)現(xiàn)的目標(biāo)也不清楚：

然后，這不像使用.startswith()那樣可讀：

當(dāng)檢查后綴時(shí)，同樣的原則也適用。下面的示例總結(jié)了如何檢查字符串是否以jpg結(jié)尾：

雖然結(jié)果是正確的，但符號(hào)有點(diǎn)難以閱讀。相反，你可以使用.endswith()，如下例所示：

與大多數(shù)這些編程建議一樣，目標(biāo)是可讀性和簡單性。在Python中，有許多不同的方法可以執(zhí)行相同的操作，因此有關(guān)選擇哪種方法的指南很有幫助。

▍何時(shí)忽略PEP 8？

對(duì)這個(gè)問題的回答：永遠(yuǎn)不會(huì)。如果遵循PEP 8，可以保證你將擁有干凈，專業(yè)和可讀的代碼。這將使你以及合作者和潛在雇主都受益。

但是，在以下情況下，PEP 8中的某些指南很不方便：

如果遵守PEP 8將破壞與現(xiàn)有軟件的兼容性；

如果圍繞你正在處理的內(nèi)容的代碼與PEP 8不一致；

如果代碼需要與舊版本的Python保持兼容；

▍幫助你的代碼遵循PEP 8的提示和技巧

PEP 8標(biāo)準(zhǔn)有很多內(nèi)容，在開發(fā)代碼時(shí)，記住所有這些規(guī)則可能是一項(xiàng)艱巨的任務(wù)。將過去的項(xiàng)目更新為符合PEP 8特別耗時(shí)。幸運(yùn)的是，有些工具可以幫助加快這一過程。你可以使用兩類工具來強(qiáng)制執(zhí)行PEP 8：linters和autoformatters。

Linters

Linters是分析代碼和標(biāo)記錯(cuò)誤的程序，它提供了有關(guān)如何修復(fù)錯(cuò)誤的建議。當(dāng)作為文本編輯器的擴(kuò)展安裝時(shí)，Linters特別有用，因?yàn)樗鼈冊(cè)谀憔帉憰r(shí)標(biāo)記錯(cuò)誤和樣式問題。下面你將看到Linkers的工作原理，然后和文本編輯器擴(kuò)展的鏈接。

最好Linters的Python代碼如下：

pycodestyle是一個(gè)根據(jù)PEP 8中的某些樣式約定來檢查Python代碼的工具。使用pip安裝pycodestyle：

可以使用以下命令終端運(yùn)行pycodestyle：

flake8是一個(gè)結(jié)合了debugger，pyflakes和pycodestyle的工具。使用pip安裝flake8：

使用以下命令從終端運(yùn)行flake8：

Autoformatters

Autoformatters是重構(gòu)ni1的代碼以自動(dòng)符合PEP 8的程序。一旦這樣的程序是black，它按照PEP 8中的大多數(shù)規(guī)則自動(dòng)編碼代碼。一個(gè)很大的區(qū)別是它將行長度限制為88個(gè)字符，而不是79。但是，你可以通過添加命令行標(biāo)志來覆蓋它，就像你一樣我將在下面的例子中看到。

使用pip安裝black。它需要Python 3.6+才能運(yùn)行：

它可以通過命令行運(yùn)行，就像Linters一樣。假設(shè)你從名為code.py的文件中開始使用以下不符合PEP 8的代碼：

然后，您可以通過命令行運(yùn)行以下命令：

code.py將自動(dòng)重新格式化為如下所示：

如果要更改行長度限制，則可以使用--line-length標(biāo)志：

另外兩個(gè)autoformatters，autopep8和yapf，執(zhí)行與black相似的操作。

▍總結(jié)

本篇主要介紹了如下內(nèi)容：

PEP 8是什么以及它存在的原因；

為什么你應(yīng)該編寫符合PEP 8標(biāo)準(zhǔn)的代碼；

如何編寫符合PEP 8的代碼；

除此之外，還介紹了如何使用linters和autoformatters根據(jù)PEP 8指南檢查代碼。

如果您想了解有關(guān)PEP 8的更多信息，那么你可以閱讀完整的文檔，或訪問pep8.org，它包含相同的信息，但格式很好。