喝咖啡休息#20。什麼是遺留程式碼以及如何使用它。讓編寫技術文件變得更容易的工具

什麼是遺留程式碼以及如何使用它

資料來源：Dou 遲早，程式設計師可能會遇到遺留程式碼。為了減輕這種熟悉的後果，我從自己的經驗中選擇了一些實用的技巧和範例 - 特別是使用遺留 Java 系統的經驗。

舊版功能

遺留程式碼是別人的程式碼，通常非常糟糕，以至於人們通常不清楚如何使用它。而如果你必須使用遺留系統，除了舊程式碼之外，你還會遇到：

• 技術過時；
• 異質架構；
• 缺乏甚至完全沒有文件。

事實上，遺留程式碼並不那麼可怕，原因如下：如果系統已經存在了這十年並且仍然可以工作，那麼它還有一些用處。也許它能賺很多錢（跟你上一次創業不同）。此外，如果這段程式碼能夠在生產環境中存活這麼長時間，那麼它是相對可靠的。因此，對其進行更改必須謹慎。首先，你要明白兩件事：

1. 我們不能不尊重一個賺了數百萬美元或每天有數千人訪問的系統。不管寫得多糟糕，這段令人作嘔的程式碼仍然可以在生產環境中存活下來並全天候（24/7）運作。

2. 由於這個系統帶來了真正的金錢，因此使用它需要承擔很大的責任。這不是一家新創公司，而是用戶明天將使用的東西。這也意味著錯誤的成本非常高，這裡的重點不在於客戶的主張，而是事情的真實狀況。

逆向工程

若要成功使用遺留程式碼，您必須使用逆向工程技術。首先，您需要仔細閱讀程式碼以準確理解其工作原理。這是強制性的，因為我們很可能沒有文件。如果我們不理解作者的思路，我們就會做出改變，後果難以預料。為了保護自己免受這種情況的影響，您還需要深入研究相鄰的程式碼。同時，不僅要向廣度邁進，還要向深度邁進。呼叫錯誤的方法在哪裡？呼叫它的程式碼從哪裡來？在遺留項目中，「呼叫層次結構」和「類型層次結構」比其他任何東西都更常用。您將不得不花費大量時間使用偵錯器：首先，請尋找錯誤，其次，了解一切是如何運作的。至於文獻記載，借助工業考古學也不失為一個好主意。在某處挖掘舊文件並與那些記得您繼承的程式碼是如何編寫的人交談是非常有用的。使用這些技術，遲早您將開始或多或少地理解程式碼。但為了防止你的努力白費，你必須立即記錄你的研究結果。為此，我建議繪製框圖或序列圖。當然，你會很懶，但你肯定需要這樣做，否則在沒有文件的六個月內，你將像第一次一樣挖掘這段程式碼。

不要重寫程式碼

開發過程中最重要的是按時打敗自己，而不是試圖從頭開始重寫整個程式碼。估計這需要多少人年。客戶不太可能願意花這麼多錢來重做已經可以使用的東西。這不僅適用於整個系統，也適用於系統的任何部分。當然，他們可能會給你一周的時間來解決所有問題，然後再給你一周的時間來修復某些問題。但他們不太可能給你兩個月的時間來重新寫系統的一部分。相反，以與其餘程式碼相同的風格實現新功能。換句話說，如果程式碼很舊，您不應該嘗試使用新的漂亮技術：這樣的程式碼將很難閱讀。例如，您可能會遇到像我們這樣的情況：系統的一部分是用Spring MVC編寫的，一部分是用裸servlet編寫的。如果在 servlet 中編寫的部分中需要添加其他內容，那麼我們以相同的方式添加它 - 在 servlet 中。

尊重商業利益

必須記住，任何任務首先都是由業務價值決定的。如果你不向客戶證明從業務角度需要進行某些改變，這些改變就不會發生。而為了說服客戶，你必須試著站在他的立場上，了解他的興趣。特別是，如果您只是因為程式碼難以閱讀而想要重構，那麼您將不被允許這樣做，並且您必須忍受它。如果實在無法忍受，可以悄悄地、一點一點地重新整理程式碼，將工作分散到各個業務票上。或者讓客戶相信，這將減少發現錯誤所需的時間，從而最終降低成本。

測試

顯然，任何專案中都需要進行測試。但是，在使用遺留系統時，也必須特別注意測試，因為所做更改的影響並不總是可預測的。您至少需要與開發人員一樣多的測試人員，否則您應該非常擅長自動化。在我們的專案中，測試包括以下階段：

1. 驗證，在單獨的分支中檢查功能的實現功能時。
2. 穩定性，當檢查發布分支時，所有功能都合併在一起。
3. 認證，即在硬體特性和配置方面盡可能接近生產的認證環境中，在略有不同的測試案例上再次運行相同的事物。

只有經歷了這三個階段，我們才能發布。有人可能認為認證是一個額外的階段，因為一切都已經在穩定階段得到澄清，但我們的經驗表明事實並非如此：有時在回歸測試期間，在另一台機器上運行第二輪，不知何故它會出來的。

正式化 DevOps 與發布

例如，釋放過程可以如下。當開發完成並且完成兩個或三個測試階段時，我們會在預計發佈時間前 36 小時向 DevOps 團隊寫一封電子郵件。之後，我們致電 DevOps 團隊並討論環境中的所有變更（我們通知他們資料庫和配置中的所有變更）。對於每次更改，我們都有一個文件（Jira 中的票證）。然後發布的時候，所有參與這個的人都聚在一起，每個人都說自己現在在做什麼：“我們上傳了數據庫”，“我們重新啟動了某某服務器”，“我們去生產環境跑回歸測試了。” ” 如果出現問題，則會啟動發布回滾程序，這與原始發布文檔中的描述完全一致 - 如果沒有這樣的文檔，我們肯定會忘記某些內容或感到困惑。

控制代碼品質

最後，由於某種原因，程式碼審查這種做法並未在所有項目中使用。如果每一段程式碼都由多個人審查，那就太好了。即使在一個非常強大的團隊中，在程式碼審查過程中總是會發現一些錯誤，如果幾個人一起看，發現的錯誤數量就會增加。此外，有時第三個或第四個審稿人會發現最糟糕的事情。

讓編寫技術文件變得更容易的工具

資料來源：Dzone 大多數程式設計師不喜歡撰寫技術文件。心理學專家 Gerald Weinberg 甚至將文件稱為「已編程的蓖麻油」：開發人員喜歡閱讀它，但他們只是討厭自己寫它。 缺乏指導或空白的路線圖會導致缺乏有關軟體不同部分如何運作的資訊。這最終會惡化程式碼最終用戶的體驗，因為在沒有文件的情況下，他們無法依賴產品的準確性和實用性。為了讓程式設計師更容易養成編寫文件的習慣，我建議專注於現在幾乎每個人都可以使用的四個優秀工具。

GitHub 頁面

如今，可能沒有一個開發人員沒有在 GitHub 上工作的經驗。對於需要儲存文件的程式設計師來說，這也是一個好地方。許多人在程式碼庫中使用標準自述文件來為使用者提供簡單的操作指南，但這並不是在 GitHub 上建立文件的唯一方法。透過GitHub Pages，您獲得的不僅是託管專案頁面，還包括文件和教學課程。您能夠直接與所有 GitHub 儲存庫進行交互，從而允許開發人員像更新程式碼一樣更新文件。此外，您可以在這裡使用Jekyll - 它可以幫助您將標記轉換為純文字或成熟的網頁。

閱讀文件

顧名思義，Read the Docs為開發人員提供了一個儲存和閱讀文件的平台。該服務的工作方式與 GitHub Pages 非常相似：程式設計師可以從他們最喜歡的版本控制系統（包括 Git、Bazaar、Mercurial 等）對文件進行更改。也支援自動版本控制和頁面建立。Read Docs 最好的部分是它的靈活性。它支援 Webhook，因此您可以自動化大部分文件建立流程。對於大多數程式設計師不想做的任務來說，這可以節省大量時間。此外，該平台上託管的所有內容都可以以多種格式向公眾開放，包括 PDF、單頁 HTML，甚至電子書格式。該服務承擔了保持文件最新的日常工作的重要部分。

泰特拉

Tettra不只是一個儲存軟體文件的平台，而且是一個完整的知識庫。當一個專案涉及一大群開發不同軟體的程式設計師時，它的效果尤其好。Tettra 可用於記錄常見問題的答案。

蜂房

Apiary對開發人員如此有用的原因是它在幫助 API 文件方面做得非常出色。該平台允許用戶用Markdown編寫文檔，包括模擬 API 呼叫。Apiary 還允許您測試 API 元素並製作原型。換句話說，它是一個文件工具和測試平台。