蛙蛙推薦：如何編寫高品質的python程式

如何編寫高品質的python程式目錄

1. 代碼規範
2. 空白項目模版
3. 單元測試
4. 文檔
5. 打包
6. 小結

代碼規範

首先閱讀下面的兩份規範，並深入理解。

• Python社區官方建議採用的Python編碼風格:PEP8 中文版
• Google SoC 建議的 Python 編碼風格:Google Python Style Guide 中文版

寫出規範的代碼是寫出高品質代碼的第一步，並且有助於培養仔細的習慣。

為了培養規範寫代碼的習慣，可以安裝flake8這個工具，它不僅可以檢查代碼風格是否符合官方建議（PEP8），而且還能找出潛在的隱患（用Pyflakes做文法分析），更逆天的是還能檢測到你有些函數寫的太複雜（代碼循環複雜度）了，更更逆天的是可以設定git commit之前必須通過這些檢查。

當然具體操作需要根據自己的項目進行一些定製，比如可以忽略E501，W293。

空白項目模版

好的開始是成功的一半，寫python代碼就從pyempty開始吧。

在github上看一下那些經典的項目，web.py,flask, pep8，他們的項目目錄都很規範，綜合借鑒了一些項目的特點，我寫了這個pyempty項目。

1. README.md 這裡寫你項目的簡介，quick start等資訊，雖然distutils要求這個檔案沒有尾碼名，但github上如果尾碼是.md的話可以直接轉換成html顯示。
2. ChangeLog.txt 該檔案存放程式各版本的變更資訊，也有一定的格式，參考web.py的ChangeLog.txt
3. LICENES.txt 這裡存放你項目使用的協議，不要編寫自己的協議。
4. requirements.txt 如果你的項目需要依賴其它的python第三方庫，在這裡一行一個寫出來，可能pip install的時候能自動幫你安裝
5. setup.py 安裝指令碼，後面詳細介紹
6. docs 裡面存放你的項目文檔，如概要設計，詳細設計，維護文檔，pydoc自動產生的文檔等，強烈推薦大家使用MarkDown格式編寫文檔
7. src 這個目錄裡存放項目模組的主要代碼，盡量不要把模組目錄直接放到根目錄，模組代碼目錄可以在setup.py裡指定的
8. tests 這個目錄存放所有單元測試，效能測試指令碼，單元測試的檔案確保以test_做首碼，這樣distutils會自動打包這些檔案，並且用python -m unittest discover -s ./ -p 'test_*.py' -v 可以直接執行這些測試

單元測試

Martin Fowler："在你不知道如何測試代碼之前，就不該編寫程式。而一旦你完成了程式，測試代碼也應該完成。除非測試成功，你不能認為你編寫出了可以工作的程式。"

我們有很多理由不寫單元測試，歸根結底是懶，雖然代碼大全上說：

大部分研究都發現，檢測比測試的成本更小。NASA軟體工程實驗室的一項研究發現，閱讀代碼每小時能夠檢測出來的缺陷要比測試高出80%左右(Basili and Selby 1987)。後來，IBM的一項研究又發現，檢查發現的一個錯誤只需要3.5個工作時，而測試則需要花費15-25個工作時（Kaplan 1995)。

但是單元測試還是讓別人相信你的代碼有很高品質的最有力證據。

好了，請詳細閱讀：

1. 深入python3.0: 單元測試-2.x也適用
2. Unit testing framework 不完整中文版

文檔

敏捷開發不是提倡什麼文檔也不寫，沒有文檔就沒有傳承和積累，輪崗或新人接手任務就會遇到很大的麻煩，所以我決定每個項目最少要寫以下文檔：

1. nalysis.model.md 概要設計文檔，不同於README.md檔案，該文檔應該寫於項目開發之前，把項目有哪些功能，大概分幾個模組等項目整體概述資訊寫一下。
2. design.model.md 詳細設計文檔，不用太詳細，至少把項目依賴哪些東西，誰依賴這個項目，重要演算法流程描述，代碼整體結構等寫出來。
3. maintain.md 維護文檔，這個我覺得最重要，你的服務都記錄哪些日誌，需要監控哪些業務指標，如何重啟，有哪些配置項等，沒這些東西，你的項目很難營運。

上面這些文檔都是項目全域性的文檔，不適合寫在docstring或注視裡，所以要有單獨的文檔。

打包

python有專門的模組打包系統distutils，你可以用這套機制把你的代碼打包並分發到Pypi上，這樣任何人都可以用pip或easy_install安裝你的模組。

如果你開發的是內部項目，還可以用mypypi架設私人的pypi，然後把項目的大的版本更新發布到內部的pypi上，組態管理人員和營運人員可以很方便的從pypi上拉取代碼安裝到測試環境或生產環境。

發布大版本的時候要給版本命名及編寫ChangeList，可以參考Git Pro的相關章節,主要記住以下幾個命令。

git tag -a v0.1 -m 'my test tag'  #給大版本命名，打Taggit describe master #給小版本命名,Git將會返回一個字串，由三部分組成：最近一次標定的版本號碼，加上自那次標定之後的提交次數，再加上一段SHA-1值git shortlog --no-merges master --not v0.1 #產生版本簡報,ChangeList

python有自己的打包機制，所以一般不要用git archive命令。

當然大版本管理用pypi管理比較合適，小的bug fix，緊急上線等好多公司都是用git直接從生產環境拉代碼更新，因為git,svn等可以很方便的撤銷某次更新，復原到某個位置。

如何管理好大版本上線和小的緊急上線，我還沒理清思路，歡迎大家參與討論。

關於打包，請閱讀如下連結：

1. Python 打包指南
2. 深入Python3.0:打包 Python 類庫
3. python打包:分髮指定檔案

小結

以上是最近學到的一些東西的總結，歡迎大家一起討論。