如何編寫高質(zhì)量的python程序

代碼規(guī)范

首先閱讀下面的兩份規(guī)范，并深入理解。

Python社區(qū)官方建議采用的Python編碼風(fēng)格:PEP8 中文版

Google SoC 建議的 Python 編碼風(fēng)格:Google Python Style Guide 中文版

寫出規(guī)范的代碼是寫出高質(zhì)量代碼的***步，并且有助于培養(yǎng)仔細(xì)的習(xí)慣。

為了培養(yǎng)規(guī)范寫代碼的習(xí)慣，可以安裝flake8這個(gè)工具，它不僅可以檢查代碼風(fēng)格是否符合官方建議（PEP8），而且還能找出潛在的隱患（用Pyflakes做語法分析），更逆天的是還能檢測(cè)到你有些函數(shù)寫的太復(fù)雜（代碼圈復(fù)雜度）了，更更逆天的是可以設(shè)置git commit之前必須通過這些檢查。

當(dāng)然具體操作需要根據(jù)自己的項(xiàng)目進(jìn)行一些定制，比如可以忽略E501，W293。

空白項(xiàng)目模版

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

在github上看一下那些經(jīng)典的項(xiàng)目，web.py,flask, pep8，他們的項(xiàng)目目錄都很規(guī)范，綜合借鑒了一些項(xiàng)目的特點(diǎn)，我寫了這個(gè)pyempty項(xiàng)目。

1.README.md 這里寫你項(xiàng)目的簡介，quick start等信息，雖然distutils要求這個(gè)文件沒有后綴名，但github上如果后綴是.md的話可以直接轉(zhuǎn)換成html顯示。

2.ChangeLog.txt 該文件存放程序各版本的變更信息，也有一定的格式，參考web.py的ChangeLog.txt

3.LICENES.txt 這里存放你項(xiàng)目使用的協(xié)議，不要編寫自己的協(xié)議。

4.requirements.txt 如果你的項(xiàng)目需要依賴其它的python第三方庫，在這里一行一個(gè)寫出來，可能pip install的時(shí)候能自動(dòng)幫你安裝

5.setup.py 安裝腳本，后面詳細(xì)介紹

6.docs 里面存放你的項(xiàng)目文檔，如概要設(shè)計(jì)，詳細(xì)設(shè)計(jì)，維護(hù)文檔，pydoc自動(dòng)生成的文檔等，強(qiáng)烈推薦大家使用MarkDown格式編寫文檔

7.src 這個(gè)目錄里存放項(xiàng)目模塊的主要代碼，盡量不要把模塊目錄直接放到根目錄，模塊代碼目錄可以在setup.py里指定的

8.tests 這個(gè)目錄存放所有單元測(cè)試，性能測(cè)試腳本，單元測(cè)試的文件確保以test_做前綴，這樣distutils會(huì)自動(dòng)打包這些文件，并且用python -m unittest discover -s ./ -p 'test_*.py' -v 可以直接執(zhí)行這些測(cè)試

單元測(cè)試

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

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

大部分研究都發(fā)現(xiàn)，檢測(cè)比測(cè)試的成本更小。NASA軟件工程實(shí)驗(yàn)室的一項(xiàng)研究發(fā)現(xiàn)，閱讀代碼每小時(shí)能夠檢測(cè)出來的缺陷要比測(cè)試高出80%左右(Basili and Selby 1987)。后來，IBM的一項(xiàng)研究又發(fā)現(xiàn)，檢查發(fā)現(xiàn)的一個(gè)錯(cuò)誤只需要3.5個(gè)工作時(shí)，而測(cè)試則需要花費(fèi)15-25個(gè)工作時(shí)（Kaplan 1995)。

但是單元測(cè)試還是讓別人相信你的代碼有很高質(zhì)量的最有力證據(jù)。

好了，請(qǐng)?jiān)敿?xì)閱讀：

深入python3.0: 單元測(cè)試-2.x也適用

Unit testing framework 不完整中文版

文檔

敏捷開發(fā)不是提倡什么文檔也不寫，沒有文檔就沒有傳承和積累，輪崗或新人接手任務(wù)就會(huì)遇到很大的麻煩，所以我決定每個(gè)項(xiàng)目最少要寫以下文檔：

1.nalysis.model.md 概要設(shè)計(jì)文檔，不同于README.md文件，該文檔應(yīng)該寫于項(xiàng)目開發(fā)之前，把項(xiàng)目有哪些功能，大概分幾個(gè)模塊等項(xiàng)目整體概述信息寫一下。

2.design.model.md 詳細(xì)設(shè)計(jì)文檔，不用太詳細(xì)，至少把項(xiàng)目依賴哪些東西，誰依賴這個(gè)項(xiàng)目，重要算法流程描述，代碼整體結(jié)構(gòu)等寫出來。

3.maintain.md 維護(hù)文檔，這個(gè)我覺得最重要，你的服務(wù)都記錄哪些日志，需要監(jiān)控哪些業(yè)務(wù)指標(biāo)，如何重啟，有哪些配置項(xiàng)等，沒這些東西，你的項(xiàng)目很難運(yùn)維。

上面這些文檔都是項(xiàng)目全局性的文檔，不適合寫在docstring或注視里，所以要有單獨(dú)的文檔。

打包

python有專門的模塊打包系統(tǒng)distutils，你可以用這套機(jī)制把你的代碼打包并分發(fā)到Pypi上，這樣任何人都可以用pip或easy_install安裝你的模塊。

如果你開發(fā)的是內(nèi)部項(xiàng)目，還可以用mypypi架設(shè)私有的pypi，然后把項(xiàng)目的大的版本更新發(fā)布到內(nèi)部的pypi上，配置管理人員和運(yùn)維人員可以很方便的從pypi上拉取代碼安裝到測(cè)試環(huán)境或生產(chǎn)環(huán)境。

發(fā)布大版本的時(shí)候要給版本命名及編寫ChangeList，可以參考Git Pro的相關(guān)章節(jié),主要記住以下幾個(gè)命令。

git tag -a v0.1 -m 'my test tag'  #給大版本命名，打Tag  
git describe master #給小版本命名,Git將會(huì)返回一個(gè)字符串，由三部分組成：最近一次標(biāo)定的版本號(hào)，加上自那次標(biāo)定之后的提交次數(shù)，再加上一段SHA-1值  
git shortlog --no-merges master --not v0.1 #生成版本簡報(bào),ChangeList  

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

當(dāng)然大版本管理用pypi管理比較合適，小的bug fix，緊急上線等好多公司都是用git直接從生產(chǎn)環(huán)境拉代碼更新，因?yàn)間it,svn等可以很方便的撤銷某次更新，回滾到某個(gè)位置。

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

關(guān)于打包，請(qǐng)閱讀如下鏈接：

Python 打包指南

深入Python3.0:打包 Python 類庫

python打包:分發(fā)指定文件

小結(jié)

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

原文鏈接：http://www.cnblogs.com/onlytiancai/archive/2012/09/11/How_to_write_high-quality_python_program.html