Architecture antipatterns and pitfalls

Neal: Hello, and welcome to the Thoughtworks Technology Podcast. I'm one of your regular hosts. Normally, we have two hosts, but because of the vagaries of holiday scheduling, I'm the only one today. That's fine because we have three guests, and it's three people that I see constantly, at least once a week, and talk to multiple times a week. I am joined today by Raju Gandhi, Mark Richards and Sarah Grey. I'll let each of them say hello and then tell you why they're here. Raju, we'll start with you.

Raju Gandhi: Thank you, Neal. I'm Raju Gandhi, and I am also one of the co-hosts of the podcast that Neal and Mark and I run. We see each other even more often than we normally do. I'm going to hand it off to Mark Richards.

Mark Richards: All right, thanks. My name is Mark Richards, and I appeared on several Thoughtworks Podcasts, so most of you probably are familiar with me. Hands-on software architect and founder of developertoarchitect.com, a website with lots of resources for architects. Sarah.

Sarah Grey: Hi, I am Sarah Grey. I am a development editor at O'Reilly Media. I'm the editor of a few of Mark, Neal, and Raju's books. This is, I think, my second time on a Thoughtworks Podcast.

Neal: All right, welcome everybody, and as you probably guessed by now, we're here to talk about a book. In fact, we're here to talk about a book that Mark Raju and I are writing, and Sarah is currently editing, called Software Architecture Patterns, Antipatterns, and Pitfalls. Let's talk a little bit about this book that is now an early release on O'Reilly. Why anti-patterns? Why not just do a book on architecture patterns? Why include anti-patterns as well?

Mark: It's interesting because patterns, which most books focus on, are things that we should consider maybe adopting, based on the certain tradeoffs of each. However, there are other things that we tend to fall into traps in. Consequently, one of the things we wanted to do in this book was not only to outline the things that work well, but also some of the practices that we do that don't work well. As a matter of fact, we've bifurcated the anti-patterns really into two pieces. Raju, I'll let you talk about those two pieces.

Raju: I just want to echo one thing that Mark said, why another book on patterns? Yes, we did want to highlight the fact that we have patterns and the other side of the coin, but I think, and this is something Neal said a while back to me, was it's important that we actually highlight the bad things, because when it comes to architecture, things are more expensive, and if you do go down the rabbit hole, it is more expensive to backtrack your way into it.

Mark: It just made me think of something where there are so many books that tell us as architects what to do, but not a lot that also tell us what not to do. [laughs] I think that's what we're trying to do in this book.

Raju: I think that when we started this book, we were just talking about patterns and anti-patterns. That was our first iteration until we realized that there's yet another-- I guess there's no third side of a coin, but whatever you call that,-

Mark: The edge.

Raju: -the edge, is the pitfalls. I think where this book stands out from the rest of the competition is we're not just telling you what you should be doing. We're also telling you what you might have to do depending on certain circumstances and the things you should never do, which are usually the pitfalls.

Neal: We're relying in this book on the Martin Fowler definition of anti-patterns. He has a great bleaky entry about anti-patterns, which has a nice visual on it that basically says that anti-patterns are not just bad things because we already have a word for bad things. It's the word bad things. An anti-pattern, instead, is something that initially looks like a pattern, but then it turns out that, in hindsight, it's a bad idea. The way that Martin describes this is it looks like a garden path lined with flowers, and it leads you into a dungeon filled with dragons. That's the idea of an anti-pattern. An anti-pattern initially looks pretty good, but that's where we distinguish this thing called a pitfall.

Mark: As a matter of fact, Neal, I have a perfect example, as a matter of fact, one I use in the book to really illustrate this difference between an anti-pattern and a pitfall. The example I use is the architecture by implication anti-pattern, and this anti-pattern is basically just starting to code without an architecture in place. The example I give is a children's soccer registration website. If a coach for that soccer team wants to put together a simple website, that coach does not need an architecture, really need just WordPress or some scaffolding.

There's a good example where this really isn't an anti-pattern. We don't need an architecture, but how it becomes an anti-pattern is the fact that this registration website, everybody loves, it just works so well, so more teams decide to use it. The states that this coach is in decides to adopt it. Pretty soon, the national children's soccer association decides, "We're going to use this website," and pretty soon, you've got thousands  and thousands of people, it needs to scale, and it has to be responsive and available.

Consequently, that's how it can turn into an anti-pattern. Now, here's the interesting definition of pitfall, though, because if we're going to build a backend financial settlement system, it's never a good idea to start that without an architecture. It's just a great example of the difference between a pitfall saying, "Just don't do this. This is a bad idea from the start," versus the best of intentions can possibly lead towards some bad results and rewrites of a system.

Neal: Yes. We differentiate anti-patterns for something that initially looks good but then turns bad, and most of the time has a remediation. There's a way to back out, which is another way of saying, something Mark was saying, that it exists on a spectrum. A little bit of it's probably okay, but then the more you do of it, the worse it gets. The sinkhole anti-pattern is another example that where a little of it is okay, but a lot of it becomes a really bad idea, and something like a layered architecture. Whereas a pitfall is bad right away, and it's often just an unrecoverable mistake.

Mark: While we're on the topic of anti-patterns and the pitfalls part of the patterns book, I really wanted to call out, which we'll talk about, I think, in a little bit or later, this idea of the unique aspects of the book, which are about the tradeoffs. It's quite interesting because when we're writing about these anti-patterns and these pitfalls, we're also letting the reader know that there still are tradeoffs associated with this.

In other words, we're not advocating a slap on the hand, don't ever do this, because there might be times when an architect might choose to adopt a particular anti-pattern because the tradeoffs associated with those balance out towards the fact that we need the pros associated with this anti-pattern, and we're going to forego the cons associated with adopting or falling into this anti-pattern. The same is even true with pitfalls, although the difference is the range of significance [chuckles] of those tradeoffs.

Sarah: Sometimes it's the least worst option, right?

Neal: Exactly. That's actually one of the things we're always striving for is least worst set of tradeoffs. That brings an interesting point which is, how does this differ it from other patterns books because, hey, there are a lot of patterns books out there? There are a lot of architecture patterns book. Why are the three of us spending our time and effort to write yet another patterns book? Mark touched on one of those things. My former colleague, Rebecca Parsons, recently introduced Mark and I somewhere as, "This is Mark and Neal. You know the tradeoff guys."

We have become known as the tradeoff guys in software architecture, because we focus a lot about that in our books because that's the fundamentals, that's our first law of software architecture that everything's a trade off. One of the things that we noticed in all these patterns books is that they talk about each pattern in complete isolation. They're all completely discreet and isolated from each other, and nobody ever talks about how they interact with each other. The interesting features of this book is we're diving in deep into how these things influence each other and trade-offs between one versus the other.

Raju: I want Sarah's take on this, being the one person in this group who actually works for a rather large publishing house, but before we go there, I think this book, yes, you two are the trade-off guys. One thing that we are doing is trying to give a qualitative analysis of how this pattern, when implemented, can change certain characteristics. I think the other two aspects that this book shines in is the aspect that we've recently finally reiterated on. We went from intersections to impacts to influences, which I think we should double-click on in a few minutes.

The final piece is the governance piece. Like Mark said, you can have a pattern and you may have implemented it correctly, or you may have opted into deliberately choosing to go with the cons of an anti-pattern, but what you want is governance. I think the influence that Neal had with his book on evolutionary architecture, notion of architectural governance and fitness functions, and the fact that we touch on that in this book makes it different than a lot of the other pattern books. Sarah, what do you want to tell us about what you see in O'Reilly?

Sarah: I absolutely agree. You see a lot of pattern books both from O'Reilly and from other publishers, and they do tend to be organized like an encyclopedia. It's one after another, more or less in isolation. They might refer to each other now and then, but there's very little in the way of comparison. There's little in the way of contextualizing those patterns in governance and in larger systems. That's what I think is really cool about this.

We've got some mechanisms within the book that make the comparisons a little easier on the reader, making it somewhat quantitative as well as qualitative, but there's a lot to chew on. You're really diving in and looking at not only what is this pattern, but what other patterns does it work with, what patterns does it definitely not work with, and giving you a little bit more scope for how you're regarding your decision about that pattern.

Neal: In many ways, we view current patterns books as being very useful, as Sarah said, as an encyclopedia of patterns, but as being woefully inadequate in that they don't treat the fact that, oh, if you combine these two patterns together, it completely changes your solution, and you can't. There's no composition or comparison between these things. That's one of the things that Mark and I have tried to do for a long time is figure out ways to make apples-to-apples comparisons between incomparable things.

If we have one legacy [laughs] publishing about software architecture, it's probably how to compare seemingly incomparable things by doing this qualitative analysis. We did this with styles in our Fundamentals book. We did it with Sagas in our Hard Parts book and database types in our Hard Parts book. We also did this in the Head First book that went all through, and of course, we're doing it now. This is one of the motivations for writing a patterns book.

We're not really seeing anybody that tries to do a qualitative analysis between, okay, you choose orchestration versus choreography, here's a list of capabilities you're interested in. How does one of those versus the other impact those capabilities? Seeing those together is, we think, a lot more interesting, a lot more contextualized, and a lot more reflective of what you see in the real world.

Mark: Another thing, if we take a look at design patterns back in the day, and even today, design patterns, in and of themselves individually, are not overly interesting. What makes, in my opinion, design patterns interesting is combining those design patterns to form a better solution.

In fact, we are taking that approach in this book by actually-- and this is one of my favorite aspects of the book, I'm just really excited about this piece-- of being able to cross-reference and index capabilities that are improved, capabilities that are diminished, also context within each of the patterns so that our second chapter is basically going to be filled with all of these tables that basically say, "If you're concerned about scalability, see these following patterns. If you're doing event-driven architecture, see these patterns. You're interested in APIs, see these patterns." The idea is now the reader has a concise collection of patterns for their specific context, and it makes the book rather multidimensional, in my opinion.

Raju: I'm sure we gave somebody at O'Reilly a little bit of heartburn  when we decided to make every chapter a separate pattern, because the thing we struggled with was a lot of pattern books tend to artificially create a taxonomy and put a set of patterns under some chapter heading. When we thought about it, there was just no way to take something like orchestration or any anti-pattern and fit it into some bigger REM.

The idea we came up with was, we're just going to have-- I think we ended up with 44 chapters in this book, because there's an introduction, there's the closing, there's a definitions chapter, and then every pattern's a separate chapter. What that free us from what lets us do is build out what Mark just said, which is allow us to cross reference and cross index between patterns without having to fight that artificial taxonomy that is built in many patterns books.

Neal: That goes toward the question too, of how did we choose which patterns ended up in this book, because there are already dozens and dozens of patterns books out there. This is the process we went through when Mark and I first outlined our Fundamentals book. We first sat down. We tried to think about everything a Fundamentals book would encompass. I think our estimate was 60 or 70,000 pages worth of-- because it was just impossible. We realized the real process was more filtering than it was accumulating.

That's what by teaching ended up within our Fundamentals book. We tried to get what is the core knowledge you need? That's really what drove our selection of patterns here is, okay, if you're a beginning software architect and you've read our Fundamentals book, what are the patterns that you really need in your tool chest to take into the world? To go into real battle for the dragons in the real world, you need some set of tools.

That's why we resisted any artificial taxonomy because they do cover a really wide breadth and depth of different flavors of things because they touch on a lot of different aspects of software architecture, including something that you don't see in a lot of software architecture patterns book, which has been Raju's life for the last six months, which is his whole family of caching patterns. He now has a PTSD about caching.

Raju: When we started talking about the caching patterns, we started with just four, and then somehow managed to just make those two. I think I'm on my sixth week of just writing out two chapters because of the detail that we have to go into this book, given that we talk about governance and we talk about the influences that could affect your caching pattern and the implementation. Yes, definitely more time than I ever thought I would spend on caching in my life.

Neal: Let's talk a little bit about the meta process of writing a book, because obviously, we don't live in the same place. All three of us live in different cities. O'Reilly has a setup that's all based on Git using AsciiDoc in this platform called Atlas. We set up weekly sync calls, and we use, just like a lot of software project, a spreadsheet for coordinating things.

Let's let Sarah talk a little bit about the management of this distributed book project and things like how we manage reviews, because AsciiDoc is great for us as writers because it's all text-based, and we can use EMAX and other fancy tools like that, but then reviewing it and posting comments and that sort of stuff is mostly the realm of things like PDF. Can you describe our workflow and how we facilitate that?

Sarah: Absolutely. It's kind of a leap from place to place. You all are writing and posting in AsciiDoc in our Git-based tool. Then, when you tell me it's ready, I am actually pulling it out, taking the AsciiDoc, and just pasting it into a Google doc. Then I'm editing it with Track Changes enabled, suggestions mode, so that I can make comments. I can just have transparency.

Often, when you're editing, there are very tiny little fiddly fixes as well as bigger picture ones. Rather than having you comparing every comma in the diff, it's a lot easier to have that suggestions mode just preserved, so that if you need to know where did this go, you can find it. To make everyone's life easier, though, once I'm done with those, I copy the document, accept the changes, put it back into the AsciiDoc tool, and push from there so that everything's updated.

Then I create a PDF and add my comments to that so that the authors are seeing really only the most important stuff. The stuff that I want to point out or the queries that are outstanding, where those track changes still are something we can go back and look at as necessary, rather than having to wade through every single change.

Neal: As much overhead as Sarah goes through, it's actually quite nice for us as authors, because some of us prefer seeing the PDF that has the annotated comments in it, because we can look and see what it is in context, because I actually like looking at  the finished version of the thing, because you can build a PDF on the regular to see what it's going to look like in its final form.

However, Raju loves diffs. [laughs] He's really into diffs, and he much prefers the diff view of that world. In fact, I've been working in AsciiDoc for over a decade, and I did not know about this little hack that Raju is going to describe here that makes it actually easier using AsciiDoc and rely on diffs. I'll let him tell the tip since it's his.

Raju: Oh, for sure. I actually discovered this when I was writing my very first book, which was JavaScript Next. What I learned is that both Markdown and AsciiDoc, you only get a new paragraph if you have an empty line between two lines. What you could do is, when you're writing out a long paragraph, you can put every sentence on a new line. Then, when Sarah edits it, you can do a word diff using Git and only see the changes per line.

Typically, in Git, the problem with Deltas is that the Delta shows up as a change of the-- If one word changes in a paragraph, the whole paragraph shows up as changed. Putting everything on a new line means that only the line that she changed actually shows up in the diff, which is awesome. Again, Sarah goes through a lot of hassle so that our lives are a lot easier. Once it does come back to us, it is much better to just view a diff and get than look at a PDF change for sure, at least in my world.

Sarah: It took a moment for me to find out that Raju was doing this and stop taking all his new lens away. [Laughs]

Mark: Well, it's interesting. I take a slightly different approach because I like Sarah's editing as a learning process. I actually take the raw edited that she creates and actually look at every word or change of a paragraph or rewording of something. Not only just to make sure it didn't change any context, but more importantly, so that I can start to see and really accommodate that particular style.

I think that really helps, and I know it helps me because as I'm writing, I remember, "Oh wait, Sarah always likes to subject before here, and this rearrangement," and so I start writing in that regard. I actually like looking at the raw pieces as opposed to just the diffs and really read it in the context of the sentence or the paragraphs that change.

Neal: It's also great for finding places where you've accidentally left room for zombies. [laughter] That's one of my favorite hacks for, you've accidentally shifted into passive voice if you can add by zombies to the sentence and it still makes sense than in passive voice.

Sarah: This actually pleases me a lot because I know that all three of those formats are getting used and appreciated by at least one of you. [laughter] `I should add too that one of the important parts of this process is having a style sheet.

We have a separate document that we keep in a G Doc that we can comment in where we document our decisions about things like, "Do we capitalize this? Do we hyphenate this? Are we hyphenating anti-pattern or not?" That kind of thing. Once we've made those decisions, we can record them in one place. "This is how we're going to style names of pattern. This is how we're going to style pieces of code when they appear in line." That kind of thing. Then we don't have to re-litigate it every single time.

Neal: One of our pet peeves is the overuse of the word performance. We're we're dedicated using responsiveness throughout instead of performance because it's a better word for describing that. That's a good example of something that's semantics that goes in the style sheet.

Mark: This is again one of the values of our weekly book calls, our sync calls. We don't call them status calls. We really call it syncing up. One of the things is when we run across a particular word, and it's not in the style guide, then we discuss it and make a decision, and Sarah adds it to the style guide. That comes up on most if not all of the sync calls. That's another value of periodically, every week, we meet at a particular time.

Neal: Let's talk about the in-person meetings because this is something that we value a lot and we've backed into this as a really effective thing, but we're completely sold on this idea now. We recently just had an in-person meeting. Actually, there's going to be an article on O'Reilly that Mark wrote up about our observations about that. As much syncing as we do online and in Google Meet and places like that, we have found, particularly for technical books like this, it's really, really valuable to get and meet over a long weekend in one of our hometowns and do some really intense-- We put an agenda together. Every time we do one of these in-person meetings, some significant revelation comes out of it. I'll let Raju and Mark talk about that.

Raju: I think the one that strikes me the most is our in-person meeting, actually in Columbus at my house, when we were writing Head First Software Architecture. I think that was when Sarah had this light bulb moment about capability versus behavior. That's when we started using it more as opposed to the word characteristic, which is something that you and Mark defined in your Fundamentals book. I think ever since then, I've always tried to say this behavior and this capability.

It's those revelations that just come from the idle banter and the camaraderie that four people sitting at a dinner table working for a weekend can reveal. You can never have that on a 30-minute or a one-hour sync call over Zoom. Even if you were to do it, I think over Zoom over a weekend, I don't think you could have it. I just think that energy that you get between four people or three people in a room breathes a creativity. I know we've had a few revelations even in the patterns and anti-patterns book. Mark's got one that we had in Atlanta last time.

Mark: Oh, yes.

Neal: A significant one.

Mark: Indeed. Let me tell you about that. Before I do, I think one of the things I've observed about these in-person gatherings that we do over a long weekend is that they're focused. In other words, we get distracted a lot when we're on a virtual call, and we're looking at other things, and we're not really fully immersed and dedicated. I think that's where that creativity really comes out and makes a huge difference. We were struggling with the anti-patterns chapters in this book.

Patterns were pretty straightforward, and we had a template for all of those where we described the context, and then the description of the pattern and how it works, and all those things. When it comes to anti-patterns, poor Raju was the first one to tackle those. Raju and I met virtually, and it's like, "Maybe this would work." We had meeting after meeting, after meeting. We met in person, and we still had not really resolved the format of the anti-pattern.

Because each anti-pattern has a particular topic associated with it, for example, the architecture by implication anti-pattern really is all about, when do I need an architecture? We realized there's a question that really comes up with these. One of the revelations that we did in person, and I am still to this day, convinced we would not have done this virtually is we said, "Why don't we, for the anti-patterns, turn the context label for the section header into a question such as, for example, architecture by implication anti-pattern, what in the world is this about?"

The context header, the actual section header that comes out in the table of content says, "When do I need an architecture?" This was a revelation. We went through every anti-pattern and pitfall, and it's like, "Oh, this is great because it talks about the context we're writing about, whether it be frozen caveman or stamp coupling anti-pattern, or any of these other pitfalls." That wasn't the significant piece. What was the significant piece? We're all looking at this idea. We said, "Wait a minute." We said, "Why don't we do this for the patterns chapters as well?"

In other words, this boring start of a chapter async chain of persistence context, and it describes what this pattern is all about. We're like, "Oh, hey, wait a minute. That's a great idea." We all took all 40 of the patterns and anti-patterns and pitfalls, and we basically formed questions on those. This is where Sarah was instrumental in really being part of that effort because she was there in person with us, and she was able to say, "Wait a minute, now you're turning that into a negative. They should all be positive statement." Again, something we wouldn't have seen until very late in the editing process, if ever.

Sarah: Then we realized that not just positive for the patterns but negative for the pitfalls.

Mark: Yes, exactly. Yes. The other really cool revelation came out that we just now created 40 different advertising blurbs about our book.

[Laughter]

Neal: It also makes the table of content so much more readable because now instead of each pattern name and then the word "context" under each one of them, it's pattern name and the fundamental question of what this pattern solves. It makes it much easier to scan and see what's going on, and it forces us as writers to focus on, okay, what fundamental problem is this pattern trying to attack? It was a great way of adding focus to both for us as writers but also to organize things even better in this.

Mark: Even, Neal, for the reader because the reader's saying, "What's a frozen caveman?" There's nothing in the table of contents that shows anything about it.

Neal: The other thing I was going to say, the last thing we'll cover here, is everything in this book is linked, but one of the things we're focusing on in this book is how things are linked together. Mark alluded to this earlier, where we're defining these common capabilities like scalability or throughput or responsiveness, and we're trying to address how each pattern affects things like scalability and throughput.

For each pattern, you've got a list of how it affects those things, but we also want to turn that inside out and say, "Okay, for scalability, which patterns will affect scalability within an architecture? That's what Mark is talking about, that second chapter, which basically takes everything and turns it inside out and gives your cross-reference across capabilities and patterns. We're actually tracking that through a Zettelkasten. If you're familiar with this family of tools, there's a popular tool called Obsidian that we're using that builds a bunch of these linkages for you. It's this incredible visual graphical display of how these things are linked to one another, that we are going to release somewhere on a website when the book is done because it's this stunning visual that's being created just by focusing on each individual pattern and thinking about how it affects all of those things, but then the tool is automatically linking all these like terms together and building this comprehensive view that is eventually going to become the second chapter of the book.

Raju: I'm very excited about actually the second chapter because I think it is an interesting take on how to look at the patterns, but I'm very excited to release that Obsidian graph that we are producing. I think it is very illuminating.

Sarah: It's really cool.

Neal: It is. It's incomplete so far, but it's complete enough now to be very cool. We can't wait to to see it, to make it out into the world at large. We need to wrap up. Sarah's got other things that she needs to go do. Thank you very much, all of my co-authors. It's good to see you yet again in yet another context. Thanks very much for having a conversation about our patterns book, and we hope that it's available for early release on O'Reilly. I'll let each of you say goodbye and say some parting words.

Mark: We should probably mention when the book's expected to be out. It is an early release now. What do you think, Sarah? Are we trying to target the end of spring or something like that of this year or maybe beginning of summer?

Sarah: Beginning of summer. We'll send it to production in spring.

Neal: It's always dangerous to ask an editor about deadlines. [Laughter]

Raju: Now that these words are immortalized on the internet, I think we have a deadline.

Sarah: Right. Don't hold me to that. [Laughter]

Mark: Great. Thanks, Mark.

Raju: I appreciate you having us again. It's always fun to be on the Thoughtworks Podcast. Thank you.

Sarah: Thank you much for having us.

Mark: Same thing. Thanks again, Neal, for having us on.

Neal: Thanks again for joining us today, and thanks for joining us for another episode of the Thoughtworks Technology Podcast and come back in a couple of weeks for another new episode. Thanks everyone.