Python 的「最最佳作法」(the Best of Best Practices)指南。(原文 by @Sloria)
概論
價值觀
- 「不要做己所不欲的工具給人用」 - Kenneth Reitz
- 「簡單永遠勝過多功能」 - Pieter Hintjens
- 「滿足 90% 的使用情境,不要管奧客」 - Kenneth Reitz
- 「優美勝過醜陋」 - PEP 20
- 「為開源貢獻」(即便最終是為了閉源項目)
一般開發準則
- 「顯明勝過隱含」 - PEP 20
- 「可讀性很重要」 - PEP 20
- 「所有人都可以解決所有問題」 - Khan Academy Development Docs
- 「一旦發現破窗(糟糕的設計、錯誤的決定、劣質代碼)立刻修復」
- 「現在就做好過一直不做」 - PEP 20
- 無情地測試,為新功能寫文檔
- 比測試驅動開發更重要的是人類驅動開發
- 這些準則也許,很可能,會改變
特別
風格
除非有適當理由,遵循 PEP 8。
命名
- 變量,函數,方法,包,模塊
lower_case_with_underscores
- 類與例外
CapWords
- 保護或內部方法
_single_leading_underscore(self, ...)
- 私有方法
__double_leading_underscore(self, ...)
- 常數
ALL_CAPS_WITH_UNDERSCORES
一般命名準則
不要用單字母變量(特別是 l
, O
, I
)(譯註:容易與數字搞混)
例外: 在非常短的塊裡,其含意從附近上下文很明顯時可以接受。
這樣可以
不要無用的標籤
用
不要
偏好「倒裝命名法」
要
不要
不要 getter、setter 方法。
要
不要
縮進
用 4 個空格,絕對不要用 Tab。以上。
import
import 整個模塊而不是單獨的符號。例如如果頂層模組 canteen
下有 canteen/sessions.py
,
要
|
|
不要
|
|
例外: 除非某些第三方代碼的文件中明確指示 import 單個符號。
理由: 這可以避免循環 import,見這個例子。
把所有 import 放在文件頂部,分三小節,每小節用一個空行隔開,三個小節分別是
- 系統 import
- 第三方 import
- 本地源 import
理由: 容易看出模塊出自哪裡。
文檔
遵循 PEP 257 的文檔字串規範。 reStructured Text 和 Sphinx 可以幫你強制這些規範。
功能明顯的函數只需要一行文檔字串。
|
|
多行文檔字串應包括
- 一行總結
- 使用情境,若適合
- 參數
- 回傳值的類型與意思,除非回傳值是
None
|
|
備註
- 使用命令體(”Return”)不要記敘體(”Returns”)
__init__
方法的文檔放在類的文檔字串中
|
|
註解
謹慎使用。偏好可讀的代碼而不是依賴大量註解,短小的方法常常比註解更有用。
不要
|
|
要
|
|
非得寫註解的時候,記得遵循「英文寫作指南」(PEP 8說的)
行長度
不要太在意,80-100 個字符在可接受範圍內。
用括號延續很長的行
|
|
測試
追求 100% 覆蓋,但不要太執著。
一般測試準則
- 用長而描述性的名字命名用例。這樣通常就不需要在測試裡寫文檔字串。
- 用例應該彼此分離,不要在用例間共享一個資料庫或網路連接,為每個用例使用一個單獨的測試用資料庫並在用完後拆除,或是使用模擬。
- 偏好用工廠來控制變量。
- 絕對不要讓沒寫完的用例通過,否則你可能會忘記他們。相反,預留一個
assert False, "TODO: 完成我"
單元測試
- 每次關注一個小功能
- 最好很快完成,但一個跑得很慢的測試勝過沒測試
- 一個用例的類對應一個類或模型通常是合理的。
|
|
功能測試
功能測試是更高級的測試,接近使用者使用你的應用的方式。通常在網路跟圖形界面應用上使用。
- 把用例寫成場景,用例跟測試方法應該描述場景中發生的事情。
- 在寫測試代碼之前先用註解講故事
|
|
注意測試用例跟測試方法合起來是一句話「Test A User can write a blog post」。