首先，讓我們來看看一些典型的錯誤文檔範例。
文檔原教旨主義者的觀點
如果人們帶著一車大活頁夾來找你，每個活頁夾都裝有一千（或更多）頁文檔，那麼你就認識到了這種情況。這裡的方法是每個抽象層級的程式碼的每個細節都需要記錄下來。文件的龐大數量使其幾乎毫無用處，並且保持更新需要付出巨大的努力。坦白說，這是浪費金錢，除非您正在為需要嚴格方法的太空船開發軟體。
敏捷類型
如果做得正確，敏捷工作並沒有什麼問題。但在某些情況下，這有點像是沒有正確記錄你的東西的藉口。第一個衝刺提供了一個通用設計文檔，該文檔不再更新，因為新的見解使其過時。在專案結束時，會出現大量不一致的文檔，幾乎沒有什麼幫助。
討厭文件的人
可能大多數開發人員都會在這個術語中認識到自己，但這裡我指的是那種毫不迴避地宣稱文檔只是浪費時間並且編寫乾淨的代碼就是 求職者資料庫 全部的類型。與敏捷一樣，我再次承認乾淨程式碼的價值。但任何合理大小的程式碼都需要更多。
任何從事程式碼工作的人都需要對架構和原理有一個總體了解。可能還需要更多一點，以避免在程式碼中進行繁瑣的搜尋以了解發生了什麼。
您需要什麼文件？
上面給出的例子可能看起來有點誇張，但老實說，事實往往離它們不遠。那麼，什麼是「正確」的文檔類型呢？根據我的經驗，我想要以下內容：
模型和演算法
模型這個術語可能有點令人困惑。我不是指軟體的模型（如基於模型的軟體開發），而是指計算主題的數學建模。此類文件特定於計算軟體。它通常充滿了方程式和推導以及對外部（通常是科學文獻）的引用。這種類型的文檔通常比程式碼本身更靜態。基本建模和最重要的演算法沒有太大變化。
使用者指南
希望有人會使用您的應用程式。如果您不是這樣，那麼正確的使用者文件就至關重要。通常，最好由未參與開發的人來編寫此內容。否則，您可能會跳過對您來說顯而易見但對剛接觸該應用程式的用戶而言不那麼明顯的內容。
使用者文件的另一個方面（與複雜的計算程式碼尤其相關）是建模和演算法背景。這與上面提到的第一個文件（模型和演算法）有一些重疊，但您不 如何取得電子郵件地址：您的數位行銷必勝法則 想用所有複雜的細節和數學內容來打擾用戶。她只需要了解她可以使用該應用程式做什麼和不能做什麼。編寫這部分需要一個既了解使用者又了解開發人員的人。這是一種罕見的鳥類。
架構
第三個重要文件是架構文件。我在這裡使用“建築”一詞可能會激怒那些對建築持形式主義觀點的人，但我希望他們能夠原諒我。我所說的架構是指能夠全面概述程式碼結構的任何東西。我傾向於將其稱為代碼地圖，因為就像真實的地圖一樣，它可以幫助您找到周圍的路。我想很多人會稱之為程式碼模型，但我使用術語架構來區分上面第一點中的模型。
最好在某種正式框架中產生此文檔，因為它迫使文檔編寫者嚴格而完整，並且所有符號的含義都很好理解。在某些情況下，可以從此文件產生程式碼框架，但根據我的經驗，這對於我們專門研究的計算密集型程式碼類型來說不太有用。其中帶有彩色框來指示程式碼的元件也同樣有幫助。
在某些情況下
交互圖或狀態圖在此層級也很有用。這對於由鬆散耦合元件組成的應用程式（例如微服務架構）尤其適用。
同樣，此類文件不會經常更改。它僅在對程式碼結構進行重大修改時進行更改，這在大多數情況下非常罕見。
開發人員指南
有價值的應用程式往往具有很長的生命週期並成為遺留程式碼。我們經常遇到最初開發於上世紀 80 年代（大約 30 年前）的應用程式。此類應用程式已由三代以上的開發人員開發。為了保持程式碼完整性，明確的開發人員指南至關重要。這將包括編碼指南（如何命名變數和類別、如何處理錯誤和環境變數等）、要使用的工具、要進行哪些測試以及如何執行它們。大多數公司都有這方面的標準文檔，但開發人員指南是應用程式文檔集的組成部分。如果開發工作轉移到其他公司或部門，則應遵循該指南。
發佈留言