如何編寫軟件架構文檔,如何編寫軟件開發文檔 今天小豆培訓網學歷教育小編就來給大家簡單介紹一下。
作者 / 以碼為梯
排版 / 以碼為梯
文章字數 / 1996
如何成為架構師系列文章（譯文）的第五篇，歡迎轉發、評論、收藏
在確認了軟件架構中的利益相關者，功能性和系統架構中的非功能性需求有哪些后，我們需要將這些內容用文檔記錄下來。這也是為什么我們要在這篇文章中討論軟件架構中的文檔的原因。
在深入討論之前，我首先要說明我們認為的架構文檔是什么樣的。不幸的是，編寫架構文檔沒有可以遵循的標準。而且，每個公司都有自己的一套關于文檔編寫的規范。 在這篇文章中，架構文檔指的是系統的頂層描述，展示整個架構工作的基本原理。架構文檔的主要目的是關聯功能性和非功能性需求。 在描述如何編寫架構文檔之前，我們需要理解為什么需要這些文檔。架構文檔的三個主要目的如下： 對于任何文檔，無論是項目文檔，開發文檔還是架構文檔，最值得關注的問題是，創建并維護文檔是否值得。對于這個問題可以通過下面的簡單公式來表示： (Cx — Cy) > Cdiff Cx代表沒有文檔時項目所需要的成本 Cy表示項目有文檔時的成本 Cdiff表示管理文檔的成本 使用以上的公式可以很容易回答是否該創建文檔，創建什么類型的文檔，以什么樣的頻率更新文檔等等類似的問題。這也可以回答對于小的項目，短期考慮或長期考慮情況下是否需要文檔這樣的問題。 但是，一個沒有文檔的項目怎么會比一個有文檔的項目成本更高呢？想象一下你有一個200人的團隊，持續五年，每個開發者在一個項目上的時長為兩年。如果沒有文檔，即使是做很小的改動也是非常混亂的。下面會給出如何維護文檔的一些小建議。 讓我們考慮一下可以在文檔中使用的架構方案和圖表類型： 這是最常見的一種圖表類型，可以以任何形式展示。通常是用于利益相關者之間交流的最方便快捷的方式。這種非正式的圖表的缺點是，不同理解程度的人，看到的圖都是一樣的，所以需要添加很詳細的說明。 Informal diagram example 它是具有一定創建規則的標準圖形方案或圖表。它的缺點是對于每個元素沒 有提供完整的描述。因此，想看懂這種圖需要特定圖表的語義知識。此外，還需要額外的軟件來完成圖表的創建，UML就是屬于這種類型的圖表。 Semiformal diagram example (C4 deployment diagram example ） 它在某種形式上是一種描述架構的語言，允許直接從創建的架構方案生成代碼，它更適用于硬件系統工程。缺點之一是：它需要特殊的軟件和知識，用于編寫和理解。 在工作中，我經常會寫文檔并維護它。接下來我分享一些編寫架構文檔的基本原則： DRY（Don’t Repeat Yourself）原則無論是在編碼還是在編寫文檔中都適用，在編寫文檔時，遇到重復的內容，使用鏈接來避免重復內容。 這有可能是重要的原則。給開發人員編寫的文檔跟給高級管理者的文檔肯定是不一樣的。因此在編寫文檔時需要弄清楚文檔為誰而寫，然后了解這些人在你的文檔中需要看到什么以及他們試圖找到什么答案。 這是文檔編寫中經常遇到的問題。比如，你提出一個問題的解決方案并以圖表的方式記錄了它。你理解它，知曉它的上下文，但是看文檔的人可能不清楚上下文，那么這種情況下對你來說一清二楚的內容卻會對他們造成混亂。因此，在寫文檔時你應該提供圖表的上下文作為描述。 此外，還可以嘗試一些標準化方法。例如，我非常喜歡使用C4標準來描述我的解決方案，因為這種方式允許你先在頂層對系統進行描述，然后深入到組件、容器和部署的細節，并且對于每個元素的描述都有合理正式的標準。 在這種情況下，您應該在花費的時間和相關性之間找到折衷方案。這里你依據本文最開始那個簡單公式來做判斷。如果維護一個項目的文檔比項目沒有文檔花費的成本更小，那編寫并維護文檔就是一件正確的事情。
