What the heck is an ADR? Do we really need to deal with another buzzword? Why should we create yet a further document?
Motivation
Let's consider the following fictitious and simplified scenario as motivation: After 15 years, a customer wants to have his desktop application available as web page. This is a huge project. A new dev is hired for this and future projects. There is a kickoff with the customer's dev and PO, as well as sales and the new dev from your company. Among others, there is this little dialogue:
Customer PO: In which framework will you implement the web page?
Sales: Angular, right?
New dev: Yes.
Customer's dev: Really? But Angular is old andinsert your favorite frameworkis much better nowadays!
Sales: Yeah, but Angular is a great fit for our needs, because *he looks intensively at the new dev
New dev: Uhm, we already have two internal applications written in Angular, right? So we will use Angular for this project as well.
Probably no one is really satisfied with this answer. The new dev asks his colleagues afterwards about the choice of Angular:
Colleague 1: I don't care about the framework, as long as you get the job done. Using another framework than the one we already use needs probably time. So, I don't think it's feasible to use another.
Colleague 2: We have always used Angular. But I am not too happy with it and I would love to try out another, newer framework.
Colleague 3: I don't like frontend development in general. I don't want to work with Angular and I don't know why we have chosen it. The guy who picked it, has already left the company.
All this feels frustrating. Although there weren't any real arguments against Angular so far. Let's make an ADR (Architectural Decision Record) and see how it helps us.
ADR 2023-12-30: Choice of frontend framework
Status: Accepted
Decision: We will use Angular
Contributors: Dev 1, dev 2, dev 3, sales colleague 1
Context
We need to choose a frontend framework for the new project. Further web projects are expected in the near future. All those web projects will be long-lived products, meaning we expect to add features and maintain them for the next 10 years at least.
Our team has already developed two small to medium sized Angular applications.
Decision's reasoning and consequences
Angular is a modern frontend framework with stability and long-time support at its core. We already have Angular expertise in our team. It is easy to extract code from our existing Angular applications into a shared library for code reuse in new projects. The existing applications will likely also benefit from the development of new code for the new project, which can be done in a shared library as well.
The fact that React has more third-party libraries available is not a problem for us. Our customers have very specific requirements and we expect that we have to develop most components by ourselves for maximal customization.
We are excited about Angular’s upcoming renaissance. Whether the renaissance will defend Angular's current second place as most used frontend framework is too early to tell. However, based on Angular's long road so far, we assume that Angular will continue to release new features, which will be easy to integrate in our code and keep our web development competitive for a long time.
We accept a high learning curve for new colleagues, which can be neglected compared to overall project time.
Options
Angular
Angular has been around since 2010 and new versions are regularly released. It is Open Source although it is developed by Google. Backwards compatibility and upgradeability have always been an important goal of Angular. It has a big community and is adopted by many big companies. Its two-way data binding and dependency injection model provide good modularity and testability.
In terms of developer interest, Angular wasn't the most famous in 2022. It has a high learning curve for beginners. Angular's default testing framework Karma was deprecated and there is no stable official replacement yet. Angular 17 addresses many of recent critics and describes itself as a renaissance.
React
React has been around since 2013 and new versions are regularly released. It is Open Source although it is developed by Meta. It has a huge community and probably the most third party libraries of all frontend frameworks. Its JSX based syntax is easy to learn. As Facebook is build upon React, it is obviously possible to build a large long-lived application with it.
Apart from a component-based approach, architectural decisions are left to developers. The state has to live within the React lifecycle, which can make separation of concerns harder. The hook based API is elegant to write but can become challenging to debug and maintain. Backwards compatibility between versions is not a major concern.
Other frameworks
We are aware that there are many other frameworks such as Vue, Svelte, Qwik, Preact, LitElement, ... Each has its own advantages and disadvantages. We don't want to invest much time in them for now, because: First, we believe that every modern frontend framework has the features we need for our projects. And second, long-term support is very important to us. Regarding the second, React and Angular are the longest available modern frontend frameworks and therefore the most interesting fits on first sight.
What have we gained through above ADR?
So we invested time in creating the ADR and added another document to our pile of documents somewhere. Let's evaluate the return to make sure this was a good investment.
An ADR makes a decision explicit. Furthermore, it gives everyone the opportunity to contribute, as it is a public document forged by or at least accepted by the full team. The dialog from the motivation section will not bother much. The feeling that maybe it wasn't a good choice, becomes an informed decision, that everyone can look up.
It also helps with future evaluation. When the expected advantages don't materialize, or the context changes, you can do a new ADR superseding the previous one, based on your learnings.
Two final things to note
First, the options were obviously not complete nor an in-depth analysis. The question of how much time you should invest is difficult to answer and depends on the context. E.g. frontend technologies are rapidly developing. New hyped frameworks frequently occur. If you spent too much time in your research, chances are high that a new framework was published in the meantime. Jokes aside, depending on the context, expected gain and your resources, I think it is OK to spend a few hours for an ADR or even a full sprint.
Second, when searching the internet, there are tons of different templates for ADRs. Some claim ADRs should be in plain texts. Others prefer tables and yet others bullet points. I think it is nice to have a common template, as it will help you to read them faster - just stick with a format that suits you.
Interesting Sources
- https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions
- https://www.ozimmer.ch/practices/2020/04/27/ArchitectureDecisionMaking.html
- https://github.com/joelparkerhenderson/architecture-decision-record
- https://2022.stateofjs.com/en-US/libraries/front-end-frameworks/
- https://survey.stackoverflow.co/2023/#overview
- https://www.imaginarycloud.com/blog/best-frontend-frameworks/
Top comments (0)