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
This book takes a long time to get going. The chapters on design paradigms (structured, object oriented, and functional) seem particularly out of place and unnecessary.
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
There are hardly any examples in this book. Chapter 33 contains an example that discusses a video sales e-commerce application. It's okay. But I didn't walk away from it with a firm idea of how I'd apply the concepts to my own systems.
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
Most developers spend most of their time working on existing systems. So, I expected Clean Architecture to be full of advice on improving existing systems. But the book is conspicuously silent on the subject.
How to create a clean architecture?
In the first half of the book you'll learn that you create a clean architecture by following the SOLID principles to break your system into components along your system boundaries (I'm paraphrasing). If you stopped reading there, you could be forgiven for having the impression that Uncle Bob would not approve of whatever you've been doing for architecture. You could also be forgiven for thinking that the few options he presents are the "right" way to do things. Yet towards the end of the book you'll read this on page 228:
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
So, if the ultimate goal of software architecture is to minimize the lifetime cost of the system, shouldn't a book on architecture help an architect make those decisions?
Unanswered questions
This book left me with a lot of unanswered questions. Where is the discussion of the economics of the various options? How do I find the optimum architecture for my system? Where's the research?
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 Code Complete, Steve McConnell talks about the tradeoffs between different non-functional requirements like reliability, dependability, correctness, maintainability, readability, etc. He explains how some requirements move together and others conflict. I would have loved to see something like that for the architecture decisions discussed in this book.
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
I spent the majority of this book slightly confused. I kind of understood what Uncle Bob was trying to say. But didn't completely get it until I read the appendix. So, let me save you some time.
An example
Imagine you are building a desktop computer for the consumer market (office computers for example). You get to choose the hardware and you are going to write the software for the whole thing (firmware, OS, drivers, applications, everything).
Would you write a monolith?
How would you go about it? Would you write a giant program (a monolith) where the code for the spreadsheet knew about the kind of disk you selected for your computer? Can you imagine updating the spreadsheet code and adding 'if' statements everywhere so that it does one thing if you have a SATA drive and another if you have a SCSI drive? And then doing the same thing for VGA vs DVI vs HDMI video? What about different paths for PS/2 vs USB mouse input? And then repeat the process for the word processor and all the other applications you intend to bundle with your computer?
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
And that's what you'll find if you look at your computer. There's embedded software in your mouse that communicates with your operating system. Yet the details are hidden from your applications. Your spreadsheet accepts standardized input without knowing or caring what kind of mouse you are using. Then when someone invents a new input device like the touchpad it works with your spreadsheet automatically.
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)
It's easy to see hardware boundaries. But the same logic that makes hardware boundaries worthwhile also applies to software boundaries. Software boundaries are just harder to see.
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
In many ways, Patterns of Enterprise Application Architecture by Martin Fowler is far superior to Clean Architecture. Fowler describes the patterns he's observed repeatedly in enterprise applications. He gives a simple example if each pattern, describes how it works, and where to use it. I found Patterns of Enterprise Application Architecture to be very readable and applicable to my systems.
Takeaways
There is valuable information in Clean Architecture but you have to work to find it.
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).
Agree or disagree. I'd love to hear your thoughts.
Enjoy this post? Please "like" it below.
Latest comments (89)
Quite ignorant
Hey Blane.
I totally agree with you.
I read the book and didn’t get the Martin’s point.
My intention was learn about clean architecture, but the book presents other points.
Here in Brazil, the people loves Martin and his book, but I think this book could be better.
First of all, thanks for sharing this thorough review of Clean Architecture. So, I see that you mentioned about Patterns of Enterprise Application Architecture and how applicable the patterns described are on your systems. Although post is from 2018 I also see some comments mentioning the same (comments from 2020).
In case you work with Java and use some of the mainstream frameworks (I know it's a details but in real life we still use them). My question is how did you manage to find the patterns from PEAA applicable today? I ask this because most of the patterns described are available and implemented by a plethora of frameworks and libraries. Just one example that comes to my mind here: Data Mapper. We have Hibernate which is very close to Data Mapper.
PS: This is a very honest question, because I'd like to give PEAA a new chance. From my perspective, today this book is good as a History book for people to understand what underpins the current libraries and frameworks highly used.
Sorry, I missed your reply. Dev.to usually sends me an email but something happened and I didn't get/see it.
First, it's entirely possible that PEAA might not be useful for you. If you architecture is dictated to you by your framework or tech lead or the shape of your existing code base, there might be little value in reading it. The book is also focused on business systems so if you are doing embedded or systems programming, etc., it's probably not the book for you.
I work primarily on legacy business systems running on the web and that's definitely PEAA's target. So PEAA offers advice on layering, web presentation patterns, several patterns for interacting with your database, session management patterns, patterns for isolating your domain logic, many, many tips for evolving the architecture of an existing system, and many other things I hoped to see addressed in Clean Architecture.
I think the larger context you might have missed is that only about 10-15% of programming effort is directed towards new projects. The vast majority of effort is directed maintaining and extending existing systems. Many of those systems are > 10 years old and may contain architectural anti-patterns or little architecture at all.
Cheers.
A 'dislike" for your post.
I found your post was picky. "Clean Architecture" is an excellent book for me, we should read it with a hindsight of our experience and past projects to appreciate it as it is. Yes, it can add more examples, more demonstrations as you demanded but then it would be bulky rather than handy as a handbook format. There could be various reasons they chose not write the book as you like.
Reasonable people can disagree about these things. The book has a 4.6/5 on Amazon.com so you are in the majority, but I stand by everything I wrote.
Thanks for taking the time to reply.
Your review is reasonable and led to other useful resources contributed by other people, that's good. For me, I love Uncle Bob's Clean Architecture. I've read "Patterns of Enterprise Application Architecture" and kind of understood and related some patterns to my work but still need much more time to digest the context and use of other patterns. A question I've been thinking about without answers is why the authors can figure out these patterns, why they are considered as good practices. In this respect, Clean Architecture sheds a light on the principles to judge software architecture as well as design patterns. Really appreciated Uncle Bob's work.
Thanks for sharing your thoughts. A few weeks ago I started reading Clean Architecture and even though I found the first few chapters really interesting I was worried that I would end up learning nothing about how to actually build large complex software. I'm not actually interested in reading another book on SOLID.
I'll take your advice and start reading Patterns of Enterprise Application Architecture.
I really like that book, and the concepts presented there. Here some comments to make you more happier about this book. I don't have access to the book right-now, I will not be able to give precise references. I will have to buy this book again. I could buy yours ;)
The Goal of architecture is addressed right at the start in the introduction. He won't go into details but it's clear. The goal of architecture is to optimize people work, not the system. Given a flat listing of all the code for a system, without boundaries or already decoupled classes into components, you and me, with different set of constraints won't derived the same architecture. Both being "optimized" for our own purposes. So there is no path to follow.
Also, adding to that, software is a living beast. You may have optimized your architecture for today, but some other day, you have to admit, things have changed. The environment, the teams, the tools, the software...
You focus a lot on the SOLID principles, but those are at the design level. They are the foundation to understand the package principles. You have to focus more on those 3 package principles and the tension space they form (it's all about compromise).
The book is about teaching principles. The recipe is following them.
Comparing Clean Architecture with Code Complete isn't fair, or is comparing apples and oranges. Code Complete is at the code level/line level. At most considering a couple of lines together, to form a class definition or a function. The scale and complexity of such elements are small and simple (but I won't explain them to my Mom ;) ). Opposite to that, in the continuum describe in the book, is architecture. You draw rectangles and arrows, but the complexity implied is so huge.
Chapter 2 is my best : A Tale of Two Values. If you have to convince a non-techy-manager-feature-oriented-I-know-nothing-about-software-development to let you structure your code, that is doing architecture, that chapter could gives you bullets. Otherwise, you will craft a Monolith. Because, you won't get up a morning with the idea "Lets build a Monolith today". Those managers make you build one (and yes, we let them do). And it's also typical for a start-up, where you have to focus on features.
I will certainly give a try to "Patterns of Enterprise Application Architecture", by Martin Fowler. I really like his work. And I totally agree (finally) that "The chapters on design paradigms (structured, object oriented, and functional) seem particularly out of place and unnecessary." I also appreciated the appendix recapping Bob's career and the polymorphisme applied to hardware.
I have been studying Clean Architecture for a while and are deciding to adopt it for my next projects. But, I also wanted to find any negative views about it, then came to this article. To my relief, your comments are more about the organisation of the "Clean Architecture" book itself and the way Uncle Bob presented the materials in the book, not really about the concepts of Clean Architecture. Yes, I too find the book not very easy and pleasant to read, but the underlying concepts about Clean Architecture are really excellent. You need to get more information from other sources, for example, Uncle Bob's video series or other people's writings on this topic about Clean Architecture.
I'm currently half way through.. .some I curious where my opinion will land once I'm finished. But I will make this one comment mid way through, that I feel will agree with our take.
The continual use of acronyms to reference the previously covered concepts can be hard to follow.
SAP, SDP, DIP, CRP, OCP, CPP....
Maybe they are just too similar? Maybe this vocabulary will come with more time / usage (which I tend not to get when just reading the book straight through)? Maybe they are a necessary evil?
Interesting point.
I don't remember the acronyms causing me problems when I read the book but I can certainly understand how they could be a problem for someone who is unfamiliar with them or for whom English isn't their native language.
Please check back when you finish the book. I'd love to hear your overall impressions.
Your title is misleading. You don't like the book does not mean you should not recommend clean architecture.
It never occurred to me that the title might be confusing. Interesting feedback. Would you agree that the first paragraph makes it clear that the post is about the book, not the concept?
It is good to read this review... I thought it was just me.
I have a hard time following your reasoning why this book is not recommendable.
You state that the stories on design paradigms were unnecessary, yet you miss to say why. So why you think these were unnecessary (beside the fact that he basically told a story before any chapter he started in that book)?
You are stating that there are too few code samples in the book, but then the book never advertised to be a code repository (in any of its pages) or explain paradigms and principles by code.
And I would say that it's not what the book is about. It's more about a way of thinking as an architect than which code or programming language is explicitly used to create a good software architecture (he states that several times in the book btw). If he would have done that, which language you think he should have used? And what exact implementation would have been good or bad?
There are always tons of ways to implement something and if talking about principles and paradigms, that would have put some heavy burdon on him and any presented implementations.
Let me clarify what I mean:
We all know it, you are implementing some boilerplate code just for a test project of yours. Very dirty, just as a proof of concept. Still, there will be people coming to you, looking at the code, starting to tell you that there are more effective, more efficient, more beautiful, better maintainable ways (append arguments here endlessly) than the test code you have just written. And they start "enlightening" you from all possible perspectives.
They expect from you to defend your decisions while all you think is "hey man, I just wanted to see how that pattern works...".
Look at the reactions about your blog posting, very divided. This forces you to answer and justify yourself and your opinion.
Now think about his book and what would have happened if he had included sample code for his presentation of general insights on clean architecture. Eventually, that would have forced him to explain how the presented code fits the all-so-good architectural paradigms he has just talked about. Also 20 years from now, would that implementation still be valid or would other languages or implementations that will arise be more fitting? See my point?
Presenting implementation examples will inevitably force you down a road you cannot get off from and therefore he simply avoided putting that burdon on him (probably there wouldn't have been an implementation that fits it all). He stayed theoretical with a groundtruth that comes from practical experience. He didn't want to get too explicit about it.
I mean look at the blue book by Eric Evans about DDD. There is as good as no code at all in that book (500+ pages btw...phew), still it's the key work to the whole DDD world and that Martin Fowler states to be one of the biggest influences he had concerning DDD (while still saying it's hard to read).
And you may have misunderstood that this book is not about THE architectural way of doing things. Rather it's a summary of all the clean architectures that presented themselves over the years. Layered, Hexagonal, Onion, Microservices and all the shebang. They all have the same thing in common, they are clean architectures. They follow the dependency rules, they allow decoupling, they cherish maintenance and testability and they allow to use little human resources to gain high production value.
The book by Fowler you recommend is great, but it's a different book with a different mindset and a different goal than clean architecture.
It's like saying Eric Evans book on DDD is bad (because it's mostly theory) and Vaugn Vernonts book on IDDD is good (because it's tailored against practice). This is simply a biased opinion, which is fine but it's not fair to expose it as if it wasn't.
To me, Clean Architecture is the perfect summary of all the principles and paradigms that play a key role in the world of architectural fundamentals. Nothing more but definetly not less.
Thanks for sharing your thoughts, Samir.
Clean Code taught me how to write clean code. It was full of examples and it was logically organized and easy to understand. I can (and do) give it to juniors and tell them to read it and apply its lessons to their code and they can do that successfully.
But I can't say the same the things about Clean Architecture. It certainly didn't teach me how to create a system with a clean architecture and I believe it would be a waste of time to give it to juniors and expect them to be able to create better architected code.
I believe many people purchased Clean Architecture with the expectation it would be on the same level as Clean Code (one of the best programming books of all time) and it's not.
With that said, plenty of people rated it 5 stars on Amazon so you're not alone in your opinion.
Let's wait for his next book: "Clean architecture by example" ! :)
I would be glad if you ever write an architecture book that fixes the issues pointed in this article.
Surely software development is far-far from being science. Till this day it is more an art, unfortunately. Value/advantage of most concepts (TDD, Clean Architecture, SOLID, OOP etc) is not substantiated by any scientific research. For a scientist, the never-ending discussions about these concepts should stop after a single scientific paper, stating that "such a such groups of developers were given a task ... under such and such criteria, and it was found that those who followed concept X produced 20% more value for the same time and 67% of them said that they also felt more satisfaction as compared to those who didn't follow it." But there are practically no such papers. (I remember only one scientific paper on comparison Scala-vs-Java development speed, but it remains unknown for 99% of Scala and Java devs.)
If your are interested by DevOps good practices back by science, read this excellent Accelerate book
You won't find SOLID, or OOP in there, but automated tests (and TDD), and Architecture.
I agree. We could benefit from more scientific research about what works and what doesn't in software development. Thanks for your comment.