Why I can’t recommend Clean Architecture by Robert C. Martin

Clean Architecture failed to meet my expectations on a number of fronts. Despite Mr Martin’s obvious passion for the topic, Clean Architecture is poorly organized, lacks examples, and is silent on working with existing systems. The author missed a major opportunity to teach us when and how to apply these lessons to our own systems. Let me explain.

Clean Architecture is a poorly organized book

The chapters on the SOLID principles are good. I enjoyed seeing the principles broken down and explained well. And I found it interesting to think about their applicability to system architecture. But Uncle Bob presents the SOLID principles like hard rules, which rubbed me the wrong way. In fact, I’m pretty sure a system that never violated the SOLID principles would be a giant mess.

However, this paragraph from page 137 is important:

The primary purpose of architecture is to support the life cycle of the system. Good architecture makes the system easy to understand, easy to develop, easy to maintain, and easy to deploy. The ultimate goal is to minimize the lifetime cost of the system and to maximize programmer productivity.

That’s a great observation. Why didn’t Uncle Bob put it in the first chapter?

Not enough examples

The appendix tells the story of how Uncle Bob came up with the SOLID principles and the rules of clean architecture. It’s loaded with examples of past projects. I think it’s the most interesting section of the book.

The book is silent on improving the architecture of existing systems

How to create a clean architecture?

This example is intended to show that architectural boundaries exist everywhere. We, as architects, must be careful to recognize when they are needed. We also have to be aware that such boundaries, when fully implemented, are expensive.

At the same time, we have to recognize that when such boundaries are ignored, they are very expensive to add in later — even in the presence of comprehensive test-suites and refactoring discipline.

So what do we do, we architects? The answer is dissatisfying. On the one hand, some very smart people have told us, over the years, that we should not anticipate the need for abstraction. This is the philosophy of YAGNI: “You aren’t going to need it.” There is wisdom in this message, since over-engineering is often much worse than under-engineering. On the other hand, when you discover that you truly do need an architectural boundary where none exists, the costs and risks can be very high to add such a boundary.

So there you have it. O Software Architect, you must see the future. You must guess — intelligently. You must weigh the costs and determine where the architectural boundaries lie, and which should be fully implemented, and which should be partially implemented, and which should be ignored.

So more than half way through the book he says that it is up to us to decide where we should put the boundaries in our systems. And that boundaries are potentially everywhere. Confusing, right?

What this book is missing

Unanswered questions

How do I decide if horizontal layering or vertical slicing or something else will minimize the lifetime cost of my system? Or if I have no clearly defined layers, how do I decide which, if any, layering strategy will minimize my lifetime costs?

I have even more questions. Where should you put your effort if you have a limited amount of time to improve the architecture of an existing system? Is separating the database from the business logic is always a good idea? Which advice should you always follow? Which advice depends on the system?

Details that would have made Clean Architecture more valuable

In Clean Architecture, project size, team size, the consequences of project failure, expected code lifetime, and other important factors are under-emphasized as drivers of architecture. For example, Healthcare.gov needs more architecture than the personal to-do list you are developing, even though they are both web apps backed by databases.

What this book is really about

An example

Would you write a monolith?

That would be a nightmare to maintain, right? So what’s the solution? Architecture! Your spreadsheet shouldn’t know what kind of mouse you’re using. Nor what kind of display you have. It should be completely oblivious to those details.

Boundaries in your computer

That’s just one of the boundaries in your computer. You’ll likely come up with hundreds of them. You might assign different teams to work on different parts of the system. You might create or adopt different specs for the various ways the different components interact.

You’re probably saying ‘duh’ at this point. It’s obvious that you wouldn’t want to change and recompile your spreadsheet every time your hardware changes. Maintenance would be a nightmare. And I agree.

Boundaries are your friend (if you use them correctly)

So, you might start with the ability to display the spreadsheet on the screen. But you might also want to save it to disk, save it to PDF, save it as a CSV, or print it. So, maybe one of the boundaries in your spreadsheet program is to have an internal data structure that represents each spreadsheet. And then you pass that structure to different code to display, save, or print it in the desired format.

If you keep the data structure completely unaware of how it is displayed, saved, or printed, then you can add a “save to XML” feature down the road without digging through all the code related to the spreadsheet data structure. And if that spreadsheet data structure is several million lines of code, you can imagine how much easier that would be.

That’s all Uncle Bob is trying to tell us in this book. You can use the SOLID principles to create boundaries in your systems that hide your implementation details, reduce complexity, and help you reduce the total lifecycle cost of your systems.

A better software architecture book


I found the chapter on embedded software one of the easiest to understand. It intuitively makes sense to avoid scattering low-level calls throughout your code base. And it also makes sense to make your logic testable in the absence of the hardware (especially since embedded software is often developed before the hardware is available). If you could only read two chapters of this book, I’d recommend you make it this one and the appendix, regardless of what kind of software you write for a living.

Overall, Clean Architecture is a tough read and Uncle Bob left me with more questions than answers. I definitely wouldn’t recommend this as your first book on software architecture (check out Patterns of Enterprise Application Architecture by Martin Fowler instead).

Originally published at smallbusinessprogramming.com on July 23, 2018.

I’m a small business programmer. I love solving tough problems with Python and PHP. If you like what you’re seeing, you should probably follow me.