高级软件工程师如何记录他们的项目

有一项任务是软件工程师们最讨厌的，然而正是这种对细节的关注，将优秀的软件工程师与糟糕的软件工程师区分开来：他们如何记录他们的项目？📝

几年前，我负责建立一个金融科技项目。由于我们决定快速行动，因此可扩展性规划并不是当务之急。我们的重点是验证这个想法，因此我们继续前进，创建具有简单解决方案的 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、经理或任何参与项目的人）有多聪明，他们都不会记得两年前做出的每一个技术决策。

当然，除非你和 10x 工程师一起工作。😆

动态图片

结论

这就是本文的全部内容。我们讨论了公司和技术团队领导如何使用 ADR 来记录他们项目的架构决策，以及它对他们、队友，甚至是他们离开后在那里工作的人有多大的帮助。