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.
Oldest comments (89)
Thanks for your recension of the book.
I've bought Clean Architecture, and it is on my short list of books to read. I'm curious if I'd share your opinion after the lecture.
You wrote:
That's all Uncle Bob. You like or hate him. He is sometimes very controversial. I have some distance to his opinion, but I want to hear what he has to say.
Absolutely. Post back here when you finish reading the book and share your thoughts.
I finished the book, so finally, I can write a comment after my reading. My first thought was to defend the book at any cost. I've been even thinking about a blog post about it. Finally, I'll only leave this comment. Blaine keeps in mind that I've nothing against your opinion. I respect others beliefs and feelings. Please, don't take this personally.
So let's start.
I can't agree. The book as a whole is well organized. Of course, there are chapters which in my opinion are unnecessary like mentioned by you chapter about design paradigms_. I share your view that sections about SOLID principles are excellent. But I think that Uncle Bob spends too much time describing those principles at this book. In my opinion, they should be mentioned, and there should be a piece of information that knowledge and a well understanding of them are required to read further.
Holy true. I've nothing to add. I think the same.
True again. There is only one chapter which describes the example location of components across multiple libraries, but it concerns newly created projects.
Yeap, a lot of unanswered questions. I had a feeling that I'm Neo and Uncle Bob is Morpheus from Matrix, and he gives me a choice between red and blue pill without telling details.
Here I disagree. The message from "Clean Architecture" by Robert C. Martin in that boundaries are the most important thing. We can organize our architecture in several ways depending on a project's needs. Furthermore, our architecture will evolve, and there will be a day we will need to reorganize our components. So we need to keep in mind to set up right, firm boundaries in our system. BTW you mentioned about boundaries in the section "What this book is really about."
I also think that database or www server is only a detail in our architecture. Thinking in that manner helped me multiple times.
I think that appendix which is a part of Uncle Bob's professional resume doesn't add anything. Yes, it's a beautiful story and a beautiful piece of history, but it's loosely coupled with the primary aim which is Clean Architecture.
To sum up, I also feel that "Clean Architecture" isn't dedicated for beginners and every reader should at least have experience and understanding of SOLID principles. At all this is not a bad book. I think that Robert C. Matin fans won't be disappointed. If you've read other Marin's book and you like his style of writing, I believe you will be satisfied. If you are an experienced software architect, it's possible that you will be bored during the reading. But again, that is only my subjective opinion. Please don't treat me like an oracle because I'm not.
Cheers.
Nice summary, Rafal.
I'm not an oracle either and I can see how you arrived at your opinions. I'm not offended; it's nice to show people see opposing points of view and let them decide for themselves.
Yeah, there's a real cult of personality issues. Certain "rules" also are highly context-dependent. Like "sure, that makes a lot of sense for Java developers..."
I like the reading material, I don't really like that it's treated like gospel.
I personally don't find him controversial. I remember his deal about "Monads" which were just plain wrong.
To be honest with you since his book Clean Code - which I must say is to me a book that every software developer should read - I do not really see what he brings on the table for today's real world problem or to challenge the state of art of software engineering. Therefore I do not find him controversial at all, he likes himself a lot and is convinced that he's right.
Kent Beck, Martin Fowler, Alistair Cockburn, Eric Evans and many others have a far more impact, I think than Uncle Bob and are much more humble which to me, is a quality which goes with intellectual honesty.
What is the story on this "deal"? I have not heard about it.
Well a while ago he posted on Twitter a statement about what a Monad is. Which gave an epic thread and some discussion on diverse communities.
Here's the Twitter thread, some discussion on Reddit
He also made a talk about Monads (also wrong) which you can find the link on this Meetup page
There other "controversies" like his stand on the guy who got fired of Google or his "tests solves everything software related" philosophy, I took the one about Monad because its less opinionated since a formal definition of a Monad exists and it's not what he said.
I just read Robert Martin's "WTF is a Monad?" presentation (slide deck, in PDF format), from about 10 years ago.
Hoo-boy, swing and a miss. Complete misunderstanding of monads.
Clean Code is a fabulous book. (Two thumbs up!)
I've not read The Clean Coder nor Clean Architecture.
Given Blaine's review, probably won't be putting Clean Architecture on my short list. Which is okay, I've already got too many books in my book queue as it is. I try to use my time to read high quality book with good signal-to-noise ratios.
However, I did not get off scott free... now I've added out Patterns of Enterprise Application Architecture by Martin Fowler to my short list.
The Martin Fowler's book is a treasure ! I agree.
This "WTF is a Monad?" was quite messy I agree !
I m pretty happy he didn't provide any concrete example because everyone despite of tech stack can grab the idea and implement it.
In my opinion Clean Architecture is a typical Uncle Bob book. And if you know other books from Uncle Bob, you will find nothing new in this one. I found this aspect a bit disappointing, too.
The last refreshing new book about architecture that I've read was this one: Langlebige Software-Architekturen (long lasting software architectures). It has a completely different approach, it's much more practical and comes with scientific analyses of existing code bases. Unfortunately it's only available in German AFAIK.
Interesting. It's too bad I can't read German.
I'm a big fan of his work but I agree that there were not as many big takeaways as I would have liked. Perhaps it's because I watched so many of his talks on youtube and there was a lot of repeated lessons.
This talk on SOLID Principles covers one of my favorite takeaways from the book: the importance of inverting dependencies. He talks about it being the biggest strength of OOP and crucial for creating good architecture.
youtube.com/watch?v=TMuno5RZNeE
I do think those with an OOP focus would enjoy his talks and books more. He tends to focus on programming in C and java.
I've enjoyed his talks on YouTube as well. I was expecting the book to go into more detail instead of basically taking the same content he covers in a 45 minute talk and turning it into a 375 page book.
Thanks for the heads up, @bosepchuk . Uncle Bob has some useful things to say, but I tend to approach his material with some caution already.
By the way, I also want to thank you for indirectly inspiring my most recent article, which I just published on here. ;)
I'm honored. BTW: I read and enjoyed your article--very insightful.
Its true Clean Architecture is a tough read. I tried reading it last month but just couldn't finish it. I expected more from Uncle Bob
Thanks for the heads up. This book was on my reading list, but now I will give Patterns of Enterprise Application Architecture a try :-)
This is the perfect description of that book. I've read it and I'm glad that there is someone else with the same opinion.
I would not recommend anything named "Enterprise" in 2018. And the book you recommend is nothing but good for first time readers, it gets into too many details, in too many patterns that are obsolete, you will end up learning too many things and remembering none.
Clean Architecture lacks a lot of stuff, but as a starter in Architecture is good overall. I read it in a few hours, it's "light". In a case, by not being so great and long, it is a great start for a developer to delve in the Architecture world, by using the same concepts he uses to code (SOLID).
My point is, even if it is a poor written book, from the Clean Architecture the reader will probably retain only 2-3 things, the "onion" schema probably is the most important, which is fine. They are powerful simple concepts that will not die of old age (like the patterns are).
Unfortunately most of these similar books are stuck in the past, with Java/.Net monoliths, which in my non-enterprise world they are obsolete. I'm still waiting for the "new age" books that takes advantage of the new advancements in the computing area.
Are you poo-pooing the Fowler book because it has the word "enterprise" in the title?
Either way, I'd take the Fowler book over Martin's book every time. Yeah, it's from 2002 and some of the info might be dated but it's still a solid reference. There are only so many sane ways you can compose enterprise software and Fowler has done a pretty great job of cataloging them.
I would like to know what you meant by that ?
I personally think that you cannot design a complex system and completely respect whatever principles you want to apply.
The aim for me is to have as fewest rules as possible and the correct focus depending on what you're working on.
Blindly following rules is bad idea and can lead to an unmaintainable system.
This post illustrates my point: dev.to/codemouse92/clean-dry-solid.... Skip down to the "When SOLID Becomes Stupidity" section if you don't want to read the whole thing.
That's what I meant as well.
I'll read the whole thing !
Thanks
It's interesting you were slightly confused throughout the book.
You had issue with the fact that the book doesn't seem to get to the point or practically give you enough examples on how to fix your current architecture. (I've paraphrased, of course. If I did so unjustly, please correct me).
May I address these two points?
1. The book builds up many ideas laterally before building on top of them.
Admittedly, some people don't learn well this way.
I'm not one of these people, but maybe you are. Or maybe my bullets don't capture the nuances of your learning style, and you have some genuinely hard problems that you believe this book's rules and principles don't help you solve.
For that I apologize, on behalf of myself and Uncle Bob.
I've seen every video on YouTube that has Uncle Bob in it. I've also read a lot of his blog posts.
And may I just assert why he holds something like SOLID as hard rules?
That could be too anecdotal. But I haven't seen the evidence that the effort is not worth it.
2. Practical examples were few and far between.
I think you bought the wrong book. This is a book on principles.
or
He then goes on to explain how to employ a principle in a that particular problem scenario. And I would say that is the value in this book.
From the foreword, Kevlin encapsulates this idea:
No book is going to work equally well for everyone. I found this book quite unhelpful and, based on the comments here, I'm not the only one. But based on your summary and several Amazon reviews, many people find the book valuable. So the reviews are split.
Clean Code is one of my favorite programming books, as it is for many programmers. And I just wanted to share my review of Clean Architecture with my colleagues on dev.to so that they might think twice before investing a significant amount of time reading this book.
Thanks for taking the time to share your thoughts.
Please share with the group if you can. I'd love to see what that looks like when it's done well.
Your comment resonates with me because you specifically discuss principles. The world we live in is highly polarized. Software development is not immune to this issue. As we gain experience as professionals, we will naturally accumulate opinions on how things should be done. This is OK. Our strong opinions relieve us of indecision. They give us a jumping off point. They help us navigate difficult problems quickly, and with confidence.
The danger is in what can happen if our opinions become absolute rules. If that occurs, our problem solving will be formulaic. Rules only apply in specific situations. Therefore our designs become less flexible, and we will have trouble with new classes of problems.
Principles can help. We should analyze our own opinions, as well as the opinions of others, and try to discern what the underlying principles are. Take the D in SOLID. DRY is a principle and is always a valid approach. However, the degree to which we apply DRY is not an absolute. This is born out with countless StackOverflow questions where people are tying themselves, and their code, in knots to try to inappropriately reuse a particular class across multiple domains because somehow they got the idea that DRY is a rule.
Learning to think, and design, in this way is a skill that comes through practice. When we first start off, there's nothing wrong with following a few absolutes. However as the scope of our responsibility grows, so must our ability to throw out those absolutes. Think of it like teaching a child that the stove is hot. When they are very young, we might tell them only that they must never touch the stove, a heater, the hot metal of a car, or a light bulb. As they get older, though, we expand on that and explain in simple terms why they must not touch these things. As they get continue to grow, we might explain in more detail the dangers of high heat. Now, we are no longer telling them specific things to avoid, but giving them a principle to help them avoid any kind of burn.
Is Clean Architecture full of Uncle Bob's opinions? Yes, and that's just fine by me. He has a lot of experience, and he's chosen to share some of it with us in the hopes that we might have an easier time. His opinion is no less valid than anybody else. We all have different experiences, and therefore different opinions. If we can learn to extract the principles and use them to augment our own experience, then we'll be better off as individuals and as an industry.