DevOps：怎麼實現源代碼註釋和系統文檔的自動化更新？

【編者按】計算機軟件傳統定義爲：軟件是計算機系統中與硬件相依存的另外一部分，軟件包括程序、數據及其相關文檔的完整集合。然而在時下的開發中，文檔的合規性每每被忽視的乾乾淨淨。本文由 Todd Waits 撰寫，講述應用程序文檔化所遭遇的3個主要挑戰，下面一塊兒展開。本文系 OneAPM 聯合高效運維編譯整理。

一般狀況下，正式的文檔（如源代碼文檔、系統需求與設計文檔，或者各種用戶文檔）會被開發團隊忽視得不折不扣，而 DevOps 中關於流程與文檔的理念能夠幫助緩解這個問題。軟件文檔一般分爲如下幾類：代碼、需求、設計、系統與用戶文檔。文檔常常會被忽略的緣由之一在於，若是不能與所依賴的開發工具（如版本控制、問題追蹤工具、wiki 及源代碼）相匹配，標準文檔工具及流程反而會對開發團隊形成妨礙，並拖慢開發速度。

本博文探討了文檔化所遇到的3個主要挑戰：流程、註釋源代碼以及系統文檔；同時解釋了以 DevOps 爲基礎的文檔能夠經過怎樣的方式使全部利益相關者得以訪問通用、可信的信息源，從而查看項目的細節。

問題流程

建立、維護用戶文檔與系統文檔時，操做人員一般會使用笨重的二進制文檔（好比 .docx）。通常來講，在文檔協做體系中，還包括一長串來來回回的電郵，或者網絡共享的文件，人們使用這些形式相互傳送文檔的更新版本。此外，專用格式（ .docx 與生成的 PDF）每每會由於跨系統操做而產生不一致，從而在跨團隊合做時，經常由於工做環境不一樣而產生數據損毀。

將二進制文件存儲在版本控制系統中是一種解決辦法，但管理多個版本的二進制文件仍舊極具挑戰。採用自動化文檔，並將它們集成在軟件開發生命週期（SDLC）中一樣存在許多問題：隨着項目的進程，這些文檔常常會更新地愈來愈少，或者被徹底廢棄。大量文檔就是個反面教材（使用不當手段解決問題）；每支團隊都應當在豐富與簡單之間找到平衡。

文檔代碼「不分家」

理想狀況下，機構應該經過規範的來源對文檔進行維護與撰寫。在討論文檔時，區分客觀信息與主觀加工過的材料很是重要。信息指的是數據或者記錄的來源，而主觀材料則是經過有序地組織信息而產生的可用終端產品，這種信息是能夠被讀者閱讀的，可能包括系統需求文檔、設計文檔、狀態報告等等。

信息能夠在不一樣的源中維護，好比在問題追蹤器、wiki 以及代碼儲存庫中；同時，信息應當存儲在實際中人們與數據交互或執行的地方。好比在尋找描述某個具體功能的文檔時，該文檔應就應該存儲在相關功能所在之處：代碼旁。

若是功能文檔沒有與代碼存在一塊兒，一旦功能有所改變，那麼工程師不止須要更新代碼，還要尋找代碼相關的文檔以便更新，文檔匱乏會拖慢開發的進度，工程師須要維護、管理並利用好這些信息。

在全部信息存好以後，咱們就能夠經過工具來撰寫你們可以閱讀並理解的文檔，來爲讀者提供信息。這些撰寫的材料一旦生成，就再也不更改，以做參考信息；生成文檔的流程是獲取最新數據的方法。將文檔材料做爲網頁上傳是保存這類文檔的一個完美手段，由於網頁顯示的老是最新版本的文檔。

源代碼

長期以來，註釋代碼的能力都屬於編程高級實踐的一部分。在過去十年間，人們爲了改進文檔體驗，爲各類語言開發了很多工具。這些工具容許開發者將相關信息歸檔，協助開發人員理解代碼。下面提到的一些工具也容許程序員在本身的文檔中將測試以可讀的方式添加進去。編譯代碼時，文檔中的測試會自動運行，若是程序員修改了代碼，卻沒有更新文檔的話，build 就會失敗。持續集成環境的快速反饋能夠協助程序員，確保其遵照正確的文檔策略。

下面的工具是樣板庫，能夠直接從源代碼註釋中生成可讀的文檔材料。

• Ruby: RDoc

• Python: Sphinx

• Java: Javadoc

• Ruby, Java, .NET, Flex: Cucumber

• C++等: Doxygen

一般管理者可能沒法清楚應該對工程師要求什麼樣的文檔。筆者就不止一次收到過這樣的需求——將每一行代碼的功能寫在註釋裏。管理者須要瞭解：這類文檔對程序員來講任務繁重，很快就能摧毀任何程序員在合理的時間內交付有商業價值內容的能力。

而在 DevOps 中，一切都應該被自動化，並找出可理解與簡單化之間的平衡點。保持「新對象應該進行文檔描述」這個思想，自動文檔化全部新對象，多是幫助程序員在代碼中添加註釋的好辦法。可是，若是沒有文檔也沒什麼影響的話（好比引發 build 失敗），你會發現一切對象都處在未歸檔的狀況下（或者用佔位符信息錯誤歸檔），從而致使返工，須要從新整理欠下的一大堆文檔。

開發人員可使用上面列出的工具來驗證文檔是否過時，實踐效果良好。若是想在一個生命週期的結尾對該項目進行記錄的話，應當在重要環節將工具打開。從項目一開始，在編寫文檔時着眼於每個最小可用的產品：記錄實際狀況，而不是得出解決方案的過程。

系統、設計和用戶文檔

撰寫系統、設計與用戶文檔的工具沒有註釋源代碼的工具種類豐富。不少時候，公司須要從頭開發本身的通用流程與基礎架構。

在近期的一篇博文中，Red Hat 的高級技術文檔撰寫者Mikey Ariel倡導使用持續集成與單元測試文檔。在該文中，Ariel 將這一過程描述爲：可以測試文檔是否遵照指南（好比，公司使用的是 backend 仍是 back-end）以及語法（利用接口使用像是Hemingway或After the Deadline之類的工具）。使用單元測試文檔的理念能夠確保公司各個部門之間文檔的標準化。

在 DevOpsDays NYC2015 關於文檔的討論中，來自 Etsy 的 Mike Rembestsy 將他們的流程描述爲「對數據中心的網絡基礎結構進行動態記錄」。Etsy 使用 Chef 來更新他們的基礎結構，同時 Chef 腳本動態地更新Nagios，監視實例與動態編輯、發佈網絡圖。經過在文檔中使用 DevOps 的手段，Etsy 的工程師將更新文檔的過程自動化，這樣在他們完成工做的時候順便就完成了這一過程。這些理念與實踐在保證文檔精準的同時，也反映了系統的當前狀態。

將文檔看成源代碼管理，使得信息版本化，並容許我的有能力維護或將較小的數據來源與各種文檔材料自動合併。處理可控數據能夠經過有效利用安排，將下降上下文切換所帶來的不利影響。切換到 DevOps 文檔流程與工做流程時，須要轉換思想，考慮什麼工具對生成文檔最爲必要。團隊在信息生成時越自動化，或者在促進信息管理時越有效，文檔的質量與可用性也就越高。最終，以 DevOps 爲基礎的文檔就可以容許全部利益相關者訪問一份通用、可信的信息源，來了解項目詳情了。

原文連接：Three Challenges to Documentation for DevOps Teams

本文系 OneAPM 工程師編譯整理。想閱讀更多技術文章，請訪問 OneAPM 官方博客。