腳本之家
你與百萬開發者在一起
來源 | 異步
最新最好的參考手冊之一，就是自帶的文檔。有鑒于此，與其把文檔頁面編輯一下再打印出來，還不如探究一下如何用好官方文檔更加有用。
標準的文檔包分成若干部分，包括在各個平臺上的文檔編寫、分發、安裝和擴展說明。只要是有關的問題，這些文檔都是尋求答案的邏輯起點。文檔最主要的兩個內容，可能也是最有用的部分，就是庫參考手冊和語言參考手冊。
庫參考手冊是絕對必要的，因為它對內置數據類型和所有內置模塊都做了解釋。語言參考手冊解釋了內核的工作方式，包括語言內核的官方術語，解釋了數據類型、語句等的工作機制。“新特性”部分也值得一讀，特別是在發布新版的時候，因為這里對新版本的所有改動都做了匯總介紹。
A.1訪問Web端的文檔對很多人而言，訪問文檔最方便的途徑就是訪問官方網站并瀏覽其中的文檔。雖然這樣需要連入Web，但優點就是內容始終是最新的。對很多項目而言，通過Web檢索其他文檔和信息是常用操作，因此始終在瀏覽器的一個標簽頁中打開并指向在線文檔，就是將參考文檔常備手邊的簡單方案。A.1.1瀏覽機器上的文檔的很多發行版本都默認包含了完整的文檔。在某些Linux發行版本中，文檔是獨立的包，需要單獨安裝。不過在大多數情況下，安裝完成后計算機中就已包含完整文檔了，訪問起來也很容易。1．在交互式shell或命令行中訪問聯機幫助信息在交互式命令解釋器中如何用help命令訪問模塊或對象的聯機幫助信息：
>>> help(int)
Help on intobject:
classint(object)
|int(x[,base])-> integer
|
|Convert a stringor number to an integer,if possible. A floating
| point argument will be truncated towards zero (this does not include a
|string representation of a floating point number!)When converting a
|string,use the optional base.Itis an error to supply a basewhen
| converting a non-string.
|
|Methodsdefined here:
...(后面是int對象的方法列表)
以上其實是解釋器調用pydoc模塊生成文檔的過程。用pydoc模塊還可以在命令行搜索文檔。在Linux或macOS系統中，如果要在終端窗口中得到同樣的輸出，只需在提示符下鍵入pydoc int即可，鍵入q則可以退出。在命令窗口中，除非已在搜索路徑中包含了庫所在目錄，否則就需要鍵入完整路徑，其中是指的用戶名。2．用pydoc創建HTML格式的幫助頁面如果希望更加順暢地查看pydoc為對象或模塊生成的文檔，可以將輸出寫入HTML文件，這樣就可以在任何瀏覽器中進行瀏覽了。為此，請將-w選項添加到pydoc命令中，在系統中將是C: .py–w int。這時就會查找int對象的文檔，pydoc會在當前目錄中創建一個名為int.html的文件，可以打開并在瀏覽器中進行查看。圖A-1顯示了int.html在瀏覽器中的樣子。
圖A-1由pydoc創建的int.html
如果由于某種原因只需要數量有限的幾頁文檔，那么這種方案就足夠用了。但大多數情況下，最好還是用pydoc提供更完整的文檔，下一節將會介紹。
3．將pydoc用作文檔服務器
除了能為任何對象生成文本文檔和HTML文檔，pydoc模塊還可以被當作服務器來使用，以便提供基于Web的文檔服務。運行pydoc時可以帶上-p和端口號參數，即可在該端口上開啟文檔服務。然后就可以輸入”b“命令，打開瀏覽器并訪問所有可用模塊的文檔，如圖A-2所示。
圖A-2由pydoc文檔服務提供的模塊文檔（部分）
用pydoc提供文檔服務有一個好處，就是它還會掃描當前目錄，在找到的模塊中由文檔字符串提取出文檔信息，即便模塊不屬于標準庫也沒關系。這樣要訪問任何模塊的文檔時，就比較有用了。但有一點必須說明，為了能從模塊中提取文檔，pydoc必須要導入模塊，這意味著它會執行模塊頂層的所有代碼。因此，對導入會帶來副作用的代碼（如第11章所述）也會被執行，因此使用此項功能時務必小心。
4．幫助文件的使用
在系統上， 3標準軟件包中包含了完整的幫助文件格式的文檔。在的安裝文件夾內的Doc文件夾中可以找到這些文件，通常位于“程序”菜單的“ 3”程序組中。打開主文件時，如圖A-3所示。
圖A-3如果習慣使用幫助文件，則該文件就是所需的全部文檔
A.1.2文檔的下載
如果想在計算機上查看文檔，但不一定或不需要運行，也可以從官方網站下載PDF、HTML或文本格式的完整文檔。如果需要能在電子書閱讀器之類的設備上訪問文檔，這樣就很方便。
A.2最佳實踐：如何成為
每種編程語言都有自己的傳統和文化，就是一個很好的例子。最有經驗的程序員，有時被稱為高手（），非常關心編碼風格，應該符合的風格和最佳實踐。此類代碼常被稱作式風格的代碼，相對Java、C或風格的代碼，更加受到尊重。
新手面臨的問題，就是該如何學習編寫式風格的代碼。了解語言及其風格需要花一些時間和努力，本附錄接下來將對如何開始提供一些建議。
成為高手的10條技巧
本節列出的技巧是針對中級人員的，也是對提升技能給出的建議。不一定要求每個人都要完全認可，但根據我多年來的觀察，這些技巧將讓你踏上成為真正高手的正途。
A.3PEP 8——編碼風格指南
本節收錄了稍作剪輯的PEP 8摘要（ ，增強提案）。PEP 8由Guido van 和Barry 撰寫，是的最接近編程風格手冊的東西。這里省略了一些比較具體的部分，但主要內容都已包括。應該盡可能讓代碼遵守PEP 8規范，代碼會由此更具風格。
訪問官方網站的文檔部分并搜索PEP，就可以獲得PEP 8全文及歷史上發布的所有其他PEP。PEP既是歷史和經驗的絕佳來源，也是當前議題和將來計劃的解釋。
A.3.1簡介
本文檔給出的編碼約定，適用于由主發行版本中的標準庫構成的代碼。有關的C實現中的C代碼風格指南，參見相應的PEP[1]。本文檔改編自Guido最初的風格指南文章，并加入了Barry風格指南的一些內容。如果與Guido的風格規則存在沖突，應該遵從本PEP。本PEP可能尚未完結（其實可能永遠不會完結）。
盲目的一致性是頭腦簡單的表現
Guido的一個重要觀點是，代碼被閱讀的次數遠多于被編寫的次數。本指南旨在提高代碼的可讀性，使各種各樣的代碼能保持風格一致。正如PEP 20[2]所述，“ ”（注重可讀性）。
風格指南是討論一致性的。與風格指南保持一致很重要。維持同一個項目內部的一致性更加重要。而保證同一個模塊和函數內部的一致性則最重要。
然而最最重要的是，知道何時應打破一致性，有時風格指南并不適用。如果心存疑慮，請采用自己的最佳判斷。請看看別人的例子并做出最佳決定。不要猶豫，盡管發出疑問。
以下是兩個打破規范的好理由。
A.3.2代碼布局1．縮進
每級縮進采用4個空格。
為了對付那些確實陳舊的代碼，又不愿做出清理，那么可以繼續沿用8個空格長度的制表符。
2．制表符還是空格
絕對禁止制表符和空格的混用。
最流行的縮進方式是只使用空格。第二流行的方式是只使用制表符。混合使用制表符和空格進行縮進的代碼，應該轉換為只使用空格的方式。如果調用命令行解釋器時帶上-t參數，它就會對非法混用制表符和空格的代碼發出警告。如果用了-tt參數，這些警告就會上升為錯誤。強烈推薦使用這些參數！
對全新的項目而言，強烈建議只用空格縮進，換掉所有的制表符。大部分編輯器都具備將制表符替換為空格的便捷功能。
3．最大行長
所有行都應限制在79個字符以內。
將行長限制在80個字符的設備還有很多最好用的字符終端工具，而且將窗口限制為80個字符寬就可以并排放置多個窗口。這些設備上的默認換行會破壞代碼的外觀，增加理解的難度。因此，請將所有行都限制在79個字符以內。對于連續的大段文字（文檔字符串或注釋），建議將行長限制在72個字符以內。
對長行進行換行的首選方案，是利用隱含的行連接特性，在圓括號、方括號和大括號內部進行斷行。必要時可以在表達式外面多加一對圓括號，不過有時候用反斜杠會更好看些。請確保對后續行進行適當的縮進。打斷二元運算符的首選位置是在運算符之后，而不是運算符之前。下面給出一些例子：
classRectangle(Blob):
def __init__(self, width, height,
color='black', emphasis=None, highlight=0):
if(width ==0and height ==0and
color =='red'and emphasis =='strong'or
highlight >100):
raiseValueError("sorry, you lose")
if width ==0and height ==0and(color =='red'or
emphasis isNone):
raiseValueError("I don't think so -- values are %s, %s"%
(width, height))
Blob.__init__(self, width, height,
color, emphasis, highlight)
4．空行頂級函數和類定義之間，請用兩個空行分隔。類內部的各個方法定義之間，請用1個空行分隔。為了讓有關聯的函數成組，可以在各函數組之間有節制地添加空行。相互關聯的一組單行函數之間，可以省略空行，如一組函數的偽實現（dummy ）。函數內部可以有節制地用空行來區分出各個邏輯部分。可將Ctrl+L（^L）換頁符接受為空白符。很多工具都將其視為分頁符，所以可以利用其進行分頁，使得文件中的關聯部分單獨成頁。5．導入導入語句通常應單獨成行，例如：
import os
import sys
不要像下面這樣寫在一起：
import sys, os
不過下面的寫法沒有問題：
from subprocess importPopen, PIPE
導入語句通常位于文件的頂部，緊挨著模塊注釋和文檔字符串后面，在模塊全局變量和常量定義之前。
導入語句應按照以下順序進行分組。
（1）標準庫的導入。
（2）相關第三方庫的導入。
（3）本地應用程序/庫——特定庫的導入。
每組導入語句之間請加入1個空行。
任何對應的聲明都應位于導入語句之后。
非常不推薦對內部包的導入使用相對導入語法。請始終對所有導入都使用絕對包路徑。即便 2.5現在已完全實現了PEP 328[3]，它的顯式相對導入語法也是強烈不推薦的。絕對導入的可移植性更好，通常可讀性也會更好。
{:—}如果是從包含類的模塊中導入類，通常可以采用如下寫法：
from myclass importMyClass
from foo.bar.yourclass importYourClass
如果上述寫法會導致本地命名沖突，就采用如下寫法：
import myclass
import foo.bar.yourclass
然后用.和foo.bar..表示類。
6．表達式和語句內的空白符
討厭之事——以下場合應避免使用多余的空白符。
x =1y = =3
錯誤：
7．其他建議始終在以下二元操作符兩側各放1個空格：賦值（=）、增量賦值（+=，-=等）、比較（==、、!=、、=、in、not、in、is、is not）、布爾（and、or、not）。在數學運算符兩側放置空格。
正確：
i = i +1
+=1
x = x *2–1
= x * x + y * y
c =(a + b)*(a - b)
錯誤：
i=i+1
+=1
x = x*2–1
= x*x + y*y
c =(a+b)*(a-b)
在用于指定關鍵字參數或默認參數值時，請勿在=兩邊使用空格。
A.4注釋
與代碼不符的注釋還不如不加注釋。只要代碼發生變化，就一定要優先保證更新注釋！
注釋應該是完整的句子。如果注釋是短語或句子，其首個單詞應該大寫，除非首個單詞是以小寫字母開頭的標識符，永遠不要改變標識符的大小寫！。
如果注釋很短，尾部的句點則可以省略。塊注釋通常由一個或多個段落組成，每個段落都由多個完整句子構成，每個句子都以一個句點結尾。
在句子末尾的句點后面，應該加上兩個空格。[4]
用英語撰寫注釋時，請采用和White編寫的書寫規范[5]。
非英語國家的程序員，請用英語撰寫注釋，除非120%確定代碼一定不會被用其他語言的人閱讀。
1．塊注釋
塊注釋通常用于緊隨其后的一些（或全部）代碼，并且縮進級別與代碼相同。每一行塊注釋都以一個“#”和一個空格開頭，注釋內部的縮進文字除外。
塊注釋內部的段落，由只包含一個“#”的空行分隔。
2．行內注釋
請有節制地使用行內注釋。
行內注釋是指與代碼語句處于同一行的注釋。行內注釋和代碼之間至少要隔開兩個空格，應該由一個“#”和一個空格開頭。
事實上，如果狀況很明了的話，是不需要用到行內注釋的。例如，以下情況就不需要：
x = x +1# Increment x
{:—}但有些時候，行內注釋還是有用的：
x = x +1# Compensate for border
3．文檔字符串
如何撰寫良好的文檔字符串（也叫），其規范在PEP 257中已名垂青史。
請為所有的公有模塊、函數、類和方法撰寫文檔字符串。非公有的方法不一定需要文檔字符串，但是應該帶有描述方法用途的注釋。該注釋應該位于def行后面。
PEP 257描述了良好文檔字符串的規范。請注意，有一點是最重要的，多行文檔字符串結尾的““”””應該自成一行，并且最好是在前面加一行空行。例如：
"""Return a foobang
Optional plotz says to frobnicate the bizbaz first.
"""
對單行的文檔字符串而言，可以讓結尾的““”””位于同一行。
本文截選自《 快速入門》（第3版）最好用的字符終端工具，[美] 娜奧米·塞德（Naomi Ceder） 著，戴旭 譯
本書是專業人士Naomi Ceder編寫的語言的綜合指南。她是一位經驗豐富的教學者，她既能讓讀者關注語言的細節，又能使其具備解決實際問題的能力。本書中配有大量貼切的示例和邊做邊學的習題，有助于讀者掌握每一個重要概念。無論讀者是要抓取網站內容還是想玩轉嵌套元組，都會贊嘆本書的清晰、專注和對細節的重視。
本書主要內容
● 明確涵蓋 3。
● 全面介紹核心庫、包和工具。
● 配備精深的習題。
● 新增5章與數據科學相關的內容。
本書專為熟悉編程概念的讀者編寫，但不要求讀者具備的使用經驗。
-END-
更多精彩
在公眾號后臺對話框輸入以下關鍵詞