軟體工程師討厭一項任務，但這種對細節的小小關注正是優秀軟體工程師與糟糕軟體工程師的區別：他們如何記錄他們的專案？
幾年前，我負責建立一個金融科技計畫。因為我們決定快速行動，所以規劃可擴展性並不是優先考慮的事情。我們的重點是驗證這個想法，因此我們繼續前進，用簡單的解決方案建立 API、架構和系統，而不是過度擔心未來。
然而，作為後端和基礎設施的負責人，我知道雖然我的記憶力可靠，但不足以回憶起六個月後的所有細節。
在我的研究中，我發現了一個我喜歡的約定： ADR ，或架構決策記錄。
它本質上是一個追蹤對架構所做的所有更改的文件：更改本身、其影響以及我們從中學到了什麼。
將其視為個人日記，但針對團隊。
為什麼它很重要？
-
人類會忘記：記錄變更對我們很有幫助，因為我們很容易忘記選擇一種架構而不是另一種架構背後的原因。
-
它使團隊變得更好：假設您已經針對某個問題嘗試了各種解決方案並記錄了成功和失敗的情況。你可以從中學習，其他人也可以，甚至是在你之後的開發人員。
-
未來的開發人員會感謝您：想像一下，一個開發人員來到程式碼庫並試圖理解為什麼五年前進行了更改。在某個地方，開發人員可能會為此苦苦掙扎，因為前工程師沒有記錄它就離開了，而且他們並不興奮。同時，在另一家公司，開發人員發現了解釋這些變更的 ADR，他們非常感激。
那你怎麼寫呢？
有幾個約定需要遵循，但您始終可以根據最適合您的方式進行調整。
啟發我的慣例在這裡：https: //adr.github.io/madr/ 。您也可以在此處查看亞馬遜的 ADR 流程： https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/adr-process.html 。
以下是您可以使用的範本範例。
# Example Title: Database Choice for User Data
## Context and Problem Statement
We need a scalable database to store and manage user data efficiently as our user base grows.
## Decision Drivers
* Scalability
* Data consistency
* Ease of integration with existing services
## Considered Options
* PostgreSQL
* MongoDB
* Amazon DynamoDB
## Decision Outcome
Chosen option: **PostgreSQL** because it provides strong data consistency and aligns well with our need for complex queries.
### Consequences
* **Good:** Supports ACID compliance, enhancing data reliability.
* **Bad:** May require more tuning to achieve high performance with large datasets.
### Confirmation
We’ll confirm this decision through periodic load tests and performance reviews as the user base scales.
## Pros and Cons of the Options
### PostgreSQL
* **Good:** ACID compliance, robust community support.
* **Neutral:** Setup and tuning can be time-consuming.
* **Bad:** Lacks native horizontal scaling.
### MongoDB
* **Good:** Schema flexibility, horizontal scaling.
* **Bad:** No ACID compliance across collections, limiting data integrity.
## More Information
For additional details, see the database performance evaluation [here](link-to-evaluation).此類文件可以存在於專案儲存庫、概念或 JIRA 中。
在我上一家公司（我擔任前端工程師）中，我們沒有針對所有架構更改的單一文件。
使用 GitLab 問題並將每個變更連結到問題分支可以幫助我們追蹤變更背後的原因，甚至在實施幾個月後也是如此。
這個做法救了我們無數次。正如我常說的，無論您或您的隊友（您的 CTO、經理或參與專案的任何人）多麼聰明，他們都不會記住兩年前做出的每項技術決策。
當然，除非您與 10 名工程師一起工作。 😆
結論
這就是本文的內容。我們討論了公司和技術團隊領導者如何使用 ADR 來記錄其專案的架構決策，以及它對他們、團隊成員甚至他們離開後在那裡工作的人有多大幫助。
如果您有經驗要分享或對本文有任何想法，請隨時在下面的評論中留言。
我總是樂於接受回饋，並樂於參與可以幫助我們所有人學習和成長的討論。
如果您喜歡這篇文章並且想要更多類似的見解，請訂閱我的時事通訊，以獲取直接發送到您收件匣的每週提示、教程和故事！
原文出處：https://dev.to/koladev/how-senior-software-engineers-document-their-project-1nf4
1) --- 會變成分隔線（上一行必須是空白）
2) # 會變成一級標題
3) ## 會變成二級標題
4) ### 會變成三級標題
5) **粗體文字**會顯示粗體文字
6) ```當第一行與最後一行會顯示程式碼
7) 請搜尋 Markdown 語法，了解各種格式