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

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

几年前，我负责搭建一个金融科技项目。由于我们决定快速推进，因此可扩展性规划并非优先事项。我们的重点是验证想法，因此我们积极推进，创建 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 来记录项目的架构决策，以及它对他们自己、团队成员，甚至他们离开后继续工作的人有多大的帮助。

如果您有经验可以分享或对本文有任何想法，请随时在下面的评论中发表。

我总是乐于接受反馈并乐于参与可以帮助我们所有人学习和成长的讨论。

如果您喜欢这篇文章并希望获得更多类似的见解，请订阅我的 时事通讯 ，每周都会将提示、教程和故事直接发送到您的收件箱！

文章来源：https://dev.to/koladev/how-senior-software-engineers-document-their-project-1nf4