Hey friends 👋 Welcome to the first issue of 2024. You know the old saying: new year, new...sletter. Ok, that was a terrible joke, but you will notice that today's issue does look a bit different. I’m experimenting with a new format this week that I’m hoping will let me keep up with all my plans for this year, including (eventually) making the newsletter a weekly thing.

I’ll have more news about that soon. For now, I hope you enjoy today’s issue as much as you enjoyed all that delicious food you had during the holidays. Let's jump in!

SOFTWARE DESIGN

Just Enough Architecture

There are two questions that always come up whenever I sit down to work on a project's architecture:

• How will I know when I’m done designing this architecture?
• How much of the overall design do I need to do up-front?

I know I’m not alone in this. These questions have been in the minds of software designers and architects for as long as humans have been building software, and there’s a good reason for that—these are very important questions, and the future of our project might depend on how we answer them.

Spending too much time working on architecture can lead us to over-engineer solutions for problems that we don’t have. On the other hand, spending too little time can lead to rapidly accumulating tech debt and the infamous “big ball of mud” architecture.

There must be a “sweet spot” somewhere in the middle—a specific amount of architecture that feels just right. So how can we find it?

How Much Architecting is Enough?

That’s the question that Professor Barry Boehm of the University of Southern California set out to answer with his research team back in 2007.

Analyzing data from 161 software projects collected over a period of 25 years, Boehm and his team discovered a clear relationship between the amount of time a team dedicated to architecture and the amount of rework they’d inevitably have to do.

Looking at the accumulation of both architecture and rework times (the solid yellow line), we’ll see that there’s a clear sweet spot that minimizes the amount of additional work a team will need to do during the lifetime of a project.

So where exactly is this sweet spot, you ask? Great question, but unfortunately there isn’t a one-size-fits-all answer that applies to every software project (that’d be nice, wouldn’t it?)

Boehm’s research discovered that the sweet spot moves around the curve depending on a number of factors, particularly:

• The size of the project, measured in lines of code, and
• How volatile it is, measured by its rate of change.

For instance, if we pay little to no attention to architecture on a relatively small project (~10,000 lines of code) our rework penalty would be around 14% of the total project time. But doing the same thing on a large project (~10 million lines of code) would result in an extra 91% of rework time between change management and large refactors—ouch.

So if we have a good enough idea of how much time a project will take (and how big it’ll be), Boehm’s research can help us estimate what percentage of time we should dedicate to architecture. This is a useful metric to keep in mind, but… it doesn’t really answer the two questions we started with:

• How will I know when I’m done designing this architecture?
• How much of the overall design do I need to do up-front?

To get the answer to these, we’ll need to dive a bit deeper.

“Just Enough” Up-Front Design

Back in the “waterfall” era, the answer to the question “How much up-front design should I do?” was simple—all of it.

The architecture of a project was defined in a big up-front design effort which was then handed off for developers to implement. This approach was impractical for a number of reasons, particularly because it didn’t let us incorporate our learnings during development back into the architecture. This is a big drawback when building software.

Agile came to the rescue in 2001 suggesting an alternative to this “make a perfect plan before you start coding” method of the waterfall approach. Unfortunately, in their efforts to avoid big up-front designs, teams of developers often ended up doing no up-front design at all, which is arguably even worse.

“Big design up-front is dumb. Doing no design up-front is even dumber.”

​

— Dave Thomas

It seems like we’re back to Boehm’s dilemma—we’re forced to choose between doing too much design, too soon, or too little, too late. There must be a sweet spot between these two extremes, right?

That’s exactly what Simon Brown suggests in his book Software Architecture for Developers. The best way to stay away from the traps that lie at the extremes is to do some design up-front, and then apply evolutionary architecture practices to incorporate your learnings during implementation back into the architecture.

Simon suggests that we spend some amount of time at the beginning of the project designing our architecture, and then stop when:

• We understand the key architectural drivers — This includes understanding what the problem we’re trying to solve is, and which quality attributes are the most important for our particular project. For instance, is performance more important than scalability? Or how important is it that multiple teams can work on this project at the same time?
• We understand the context and scope of what we’re building — This means that if someone asks us what are we building, we should have a clear answer in mind. “We’re building a React app” is not a good enough answer—we should be able to articulate what the main components of our application are (e.g. any APIs, databases, servers, or third-party services involved) and how they will communicate with each other.
• We are confident that our design satisfies the key architectural drivers — Once we get clarity on both the problem and the solution, it’s important to take a step back and ask ourselves if our solution (the architecture) actually solves the problem. It’s not uncommon to get so mixed up on a technical solution that we forget what the actual requirements are.
• We have a way to communicate our vision to other people — At a minimum, we should have a design spec describing the architecture and any architecturally significant decisions we’ve made. Drawing good diagrams helps a lot in communicating our design to the rest of the team. Simon suggests using his own C4 model for visualizing architecture.
• We have identified our high-priority risks — We don’t need to eliminate all risks as part of our initial design, but we should at least identify and be comfortable with the level of risk we’re taking on. For instance, if our architecture relies on a framework or technology that no one in the team has experience with, we should document the risks associated with that decision. Running prototypes and proof of concepts is a great way to mitigate risks at this stage.

If we can confidently check all of those items, it’s time to stop thinking about the problem and start building. Remember, we’re not trying to create a perfect design, we’re aiming for “just enough.”

Think of your initial design as a starting point to set the general direction of your project—not as a detailed plan that needs to be followed step-by-step. As you make progress in your project, you’ll have the opportunity to iterate on your design and adjust as needed, so don’t think that every decision you make at this point is set in stone.

Now, all this talk about architecture is great and all, but you might be wondering:

“I’m a frontend developer, Maxi. How does all this stuff apply to me?”

Well, I’m glad you asked! As I mentioned in the previous issue of the newsletter, I’m working on a FREE Frontend Architecture Workshop that covers all this stuff (and more) in great detail.

We’ll go through the entire architecture process of a new project (complete with functional requirements and a real UI design spec), all from a frontend development perspective. I’ll also share a template that you can use on your next design or architecture project.

🔜 This workshop is one of my three big projects for 2024, and I couldn’t be more excited about it. Keep an eye on the newsletter—I’ll share more details about it soon.

ARCHITECTURE SNACKS

Links Worth Checking Out

📕 READ

1. It makes me so happy to see Dan Abramov writing on his blog again. This year he’s taking us on a journey to re-discover React from first principles.
2. Mayank wrote a thoughtful article on the good, the bad, the ugly, and the uglier parts of React Server Components.
3. It’s the start of a new year and it’s the perfect time to revisit this classic essay by Julia Evans on getting your work recognized with a brag document.
4. If you need a field guide to help you navigate the state of JavaScript frameworks in 2024 (and who doesn’t?), Ryan Carniato wrote a great article about it.

​

🎥 WATCH

​Minimum Viable Architecture by Randy Shoup​

This talk is definitely worth a watch if you enjoyed today’s issue on “just enough” architecture. Randy is an experienced software architect who has worked at Google, eBay, StitchFix, and WeWork, and in this talk, he shares his learnings and recommendations for coming up with the most appropriate architecture for your product’s stage of evolution.

​

🎧 LISTEN

​The Big Build Bool Bonanza II​

I really enjoyed this chat between Jake and Surma on the latest episode of their new podcast, Off The Main Thread. It’s all about build tools such as Vite, Rollup, and Bazel, their pros and cons, and the very important role they play in modern web development.

That’s all for today, friends! Thank you for making it all the way to the end. If you enjoyed the newsletter, it would mean the world to me if you’d share it with your friends and coworkers. (And if you didn't enjoy it, why not share it with an enemy?)

Did someone forward this to you? First of all, tell them how awesome they are, and then consider subscribing to the newsletter to get the next issue right in your inbox.

I read and reply to all of your comments. Feel free to reach out on Twitter or reply to this email directly with any feedback or questions.

Have a great week 👋

– Maxi