最近看了不少代碼，也寫了不少代碼，所以在看和寫之間發現了很多的問題，真的是很多，至少從我的認識來看，有幾個地方有很大的改進空間，這里不准備把所有的問題都列舉出來，所以就先挑選一個比較明顯得來和大家聊聊。回顧流行開源項目的成功，除了功能上的剛需之外，文檔也是必不可少的一個環節，沒有良好文檔的開源項目幾乎不可能說是流行的，因為很少人會因為你說了一句使用我的項目就可以怎么怎么樣就傻不溜秋得用你的。從我以前開源的項目中大家可能會發現一個比較大的問題就是文檔工作做得確實不咋地。
項目中的文檔我認為可以分為直接文檔和間接文檔兩部分，直接文檔就是 README/Read the docs 這類的可以直接閱讀的文檔，而間接文檔就是代碼中的注釋了。別人在閱讀你的項目的時候，首先，直接文檔可以讓大家對你的項目有一個直觀的認識，知道你的項目是干嘛的，大概的實現思路/算法是怎樣的；而代碼注釋就是別人在驗證你的項目是否真如你文檔所說，實現得是否良好的一種參考，所以兩種文檔都是很重要的。
在 Python 中，因為 docs comment 的存在，可以讓這兩種文檔歸一，其實就是將 comment 抽離出來轉化為可以直接閱讀的 Document，雖然這有點理想化，但是在一定程度上減少了我們編寫文檔的難度和復雜度。本文就如何編寫這樣的 Comment 進行一個簡單的總結，同時也是對自己的一個改進。
Google coding-style guide
玩 Python 的同學應該都知道 Python 沒有一個業界的代碼規范，而 PEP8 這些也不並不能完全對我們的開發起到很好得規范和知道作用。反而，看現在很多人的代碼，發現 google coding style 的接受度更高，所以，不妨多參考一些。
模塊注釋
在 Python 中，每個文件其實都是一個自成模塊，所以我就稱文件注釋為模塊注釋，模塊注釋一般就是解釋該模塊是干嘛用的，以及如何使用該模塊等信息，同時，在構建工具之后就變成了文檔的主要內容了。不妨我們來看下 requests 的注釋：

可以發現其實這份注釋還是比較清晰的，可以分為幾個部分，分別是：
- 功能介紹
- 使用 Demo 示例以及參數/返回值等
- 版權之類的說明
這算是一份比較標准化的注釋了，至於注釋的風格，我們可以參照 reStructuredText Primer 這份說明進行練習。
類注釋
類的注釋的話又稍微復雜一些，除了必要的類說明和使用示例之外，你還需要對類的夠贊函數進行參數描述，因為 python 的構造函數是 __init__，而我們通常文檔是直接看類的說明，所以這里寫在類上很重要！如果你的類存在必要的公共屬性，需要對外暴露出來，那么也應該標注出來。我們可以參考一下 Flask 的示例：

前面洋洋灑灑得寫了很多說明，然后后面就對構造函數的參數進行了描述。
函數注釋
函數的注釋應該是最復雜的，因為我們不僅僅最函數的功能進行描述，還要關注函數的參數和返回值，參數又需要描述參數的意義，還要描述參數的類型，返回值也是如此，所以我們也來看看 Celery 的一個示例：

這里只有對函數的解釋，注意事項還有返回值，除此之外，我們還經常用的有：
- Args
- Returns
- Raises

從源碼構建文檔
當我們將我們的源碼的注釋都注釋得七七八八了，覺得是時候編一份文檔看看效果如何了，那么你是應該看看下面的介紹啦！
當然，我還是參考一些流行項目的做法，看看人家的文檔是怎么做的，說實話，我看過的這么多個項目的文檔中，Flask 確實是寫得比較好的，當然，Django 的也是不錯，不過它的文檔過於人工修飾，從源碼中還原度沒有那么高。所以這里我以 Flask 為例來看看開源項目是如何做注釋文檔化的。
要想了解自然先嘗試一遍，不是太麻煩，將 Flask 的源碼 clone 下來之后，只需要簡單得使用 make docs，稍等片刻，你就講得到 docs 的編譯版本，默認你會得到 html 版本，位置就在源碼目錄的 _build/html 目錄下。但是，看看 Makefile 再看看 docs 目錄你可能又會疑惑，因為 docs 里面已經放置了 rst 文件了，所以這個時候的問題就是如何從 py 文件中抽離 rst 文件！
其實這些問題對於一些工具來說都是很簡單的，Flask 用的是 sphinx，這個工具被 Python 世界的大多數開源項目所青睞，所以也成為了一個事實上的文檔標准。使用 sphinx 可以讓我們輕松得解決兩個問題：
- 抽離 python 注釋
- 將代碼文檔化
操作過程只是兩句命令就可以解決的問題：
- 將代碼中的文檔注釋抽離出來：
sphinx-apidoc -F -o docs flask - 將文檔轉換成 html 形式：
sphinx-build -b html . _build/html- 或者在第一步的基礎上更直接點：
make html
- 或者在第一步的基礎上更直接點：
這樣，你就將你之前的努力都轉化成可以被人直觀接受的文檔了！這里是我轉化過的一個示例：

很多時候我們可能對默認轉化出來的文檔不是很滿意，但是，沒關系，我們可以在完成第一步之后編輯 rst 文件，然后調整到我們滿意之后，再 make html，這樣就會好很多！