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 是應用效能管理領域的新興領軍企業，能幫助運維人員進行故障預警和定位，減少業務系統維護的工作量，同時還能提供可追溯的效能資料，量化運維部門的業務價值。想告別加班熬夜，歡迎免費註冊體驗！