從開源項目看python代碼注釋

標籤：turn   意義   dem   alt   檔案   str   www.   目錄   存在   

最近看了不少代碼，也寫了不少代碼，所以在看和寫之間發現了很多的問題，真的是很多，至少從我的認識來看，有幾個地方有很大的改進空間，這裡不準備把所有的問題都列舉出來，所以就先挑選一個比較明顯得來和大家聊聊。回顧流行開源項目的成功，除了功能上的剛需之外，文檔也是必不可少的一個環節，沒有良好文檔的開源項目幾乎不可能說是流行的，因為很少人會因為你說了一句使用我的項目就可以怎麼怎麼樣就傻不溜秋得用你的。從我以前開源的項目中大家可能會發現一個比較大的問題就是文檔工作做得確實不咋地。

項目中的文檔我認為可以分為直接文檔和間接文檔兩部分，直接文檔就是 README/Read the docs 這類的可以直接閱讀的文檔，而間接文檔就是代碼中的注釋了。別人在閱讀你的項目的時候，首先，直接文檔可以讓大家對你的項目有一個直觀的認識，知道你的項目是幹嘛的，大概的實現思路/演算法是怎樣的；而代碼注釋就是別人在驗證你的項目是否真如你文檔所說，實現得是否良好的一種參考，所以兩種文檔都是很重要的。

在 Python 中，因為 docs comment 的存在，可以讓這兩種文檔歸一，其實就是將 comment 抽離出來轉化為可以直接閱讀的 Document，雖然這有點理想化，但是在一定程度上減少了我們編寫文檔的難度和複雜度。本文就如何編寫這樣的 Comment 進行一個簡單的總結，同時也是對自己的一個改進。

Google coding-style guide

玩 Python 的同學應該都知道 Python 沒有一個業界的代碼規範，而 PEP8 這些也不並不能完全對我們的開發起到很好得規範和知道作用。反而，看現在很多人的代碼，發現 google coding style 的接受度更高，所以，不妨多參考一些。

模組注釋

在 Python 中，每個檔案其實都是一個自成模組，所以我就稱檔案注釋為模組注釋，模組注釋一般就是解釋該模組是幹嘛用的，以及如何使用該模組等資訊，同時，在構建工具之後就變成了文檔的主要內容了。不妨我們來看下 requests 的注釋：

?

可以發現其實這份注釋還是比較清晰的，可以分為幾個部分，分別是：

1. 功能介紹
2. 使用 Demo 樣本以及參數/傳回值等
3. 著作權之類的說明

這算是一份比較標準化的注釋了，至於注釋的風格，我們可以參照 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，這樣就會好很多！

Reference

1. Google Python Style Guide
2. reStructuredText Primer

從開源項目看python代碼注釋