《像計算機科學家一樣思考Python》——4.9 文檔字元串

本節書摘來自異步社群《像計算機科學家一樣思考python》一書中的第4章，第4.9節，作者[美]allen b. downey，趙普明 譯，更多章節内容可以通路雲栖社群“異步社群”公衆号檢視。

文檔字元串（docstring）是在函數開頭用來解釋其接口的字元串（doc是“文檔”documentation的縮寫）。下面是一個示例：

這裡的文檔字元串是一個使用三引号括起來的字元串。三引号字元串又稱為多行字元串，因為三引号允許字元串跨行表示。

文檔字元串很簡潔，但已經包含了其他人需要知道的關于函數的基本資訊。它精确地解釋了函數是做什麼的（而不會涉及它是如何實作的細節）。它解釋了每個形參對函數行為的影響效果以及每個形參應有的類型（如果其類型并不顯而易見）。

編寫這類文檔是接口設計的重要部分。一個設計良好的接口，也應當很簡單就能解釋清楚；如果你發現解釋一個函數很困難，很可能表示它的接口設計有改進的空間。