Software Architecture for Developers • Simon Brown & Stefan Tilkov

This interview was recorded for the GOTO Book Club.
http://gotopia.tech/bookclub

Simon Brown - Author of "Software Architecture for Developers Vol. 2"
Stefan Tilkov - Co-founder & Principal Consultant at INNOQ

DESCRIPTION
Software architecture concepts will help software developers not only advance their careers but also do a better job in their current work. Simon Brown, the creator of the C4Model talks to Stefan Tilkov about why software architecture is something that every developer should understand, how the C4 Model can help with that and why diagrams are so useful in software development.
The interview is based on Simon's book "Software Architecture for Developers Vol. 2": https://leanpub.com/visualising-software-architecture

Read the full transcription of the interview here:
https://gotopia.tech/bookclub/episodes/software-architecture-for-developers-c4-model

RECOMMENDED BOOKS
Simon Brown • Software Architecture for Developers Vol. 2 • https://leanpub.com/visualising-software-architecture
Mark Richards & Neal Ford • Fundamentals of Software Architecture • https://amzn.to/3qmELt7
Gregor Hohpe • The Software Architect Elevator • https://amzn.to/3tY8evH
Michael Keeling • Design It! • https://amzn.to/37y4OGH
George Fairbanks • Just Enough Software Architecture • https://amzn.to/3bbjqg3
Nick Rozanski & Eoin Woods • Software Systems Architecture • https://amzn.to/3ajYjsv
Peter Coad, Eric Lefebvre & Jeff de Luca • Java Modeling In Color With UML • https://amzn.to/3bVDTHd
Eric Evans • Domain-Driven Design • https://amzn.to/3tnGhwm
Grady Booch, James Rumbaugh & Ivar Jacobson • The Unified Modeling Language Reference Manual • https://amzn.to/2OA1Qv1

https://twitter.com/GOTOcon
https://www.linkedin.com/company/goto-
https://www.facebook.com/GOTOConferences

Looking for a unique learning experience?
Attend the next GOTO conference near you! Get your ticket at https://gotopia.tech

SUBSCRIBE TO OUR YOUTUBE CHANNEL - new videos posted almost daily.
https://www.youtube.com/GotoConferences

Twitter
Instagram
LinkedIn
Facebook

Looking for a unique learning experience?
Attend the next GOTO conference near you! Get your ticket: gotopia.tech

SUBSCRIBE TO OUR YOUTUBE CHANNEL - new videos posted daily!

Transcript

Intro

Stefan Tilkov: This conversation actually serves a dual purpose, Actually, triple purposes, in fact. I'm getting a nice conversation and I also get an audio track for a case podcast and we get a video track for the GOTO Book Club. This is just about perfect. So, Simon, why don't you start by telling everyone who you actually are and what you do for a living.
 
Simon Brown: I'm an independent consultant mostly specializing in software architecture. My background is as a software developer, building software either for or with customers. I used to work in a consulting environment. Now I get to do two things. I get to hopefully, one day again fly around the world and run architecture workshops and I also have another company called Structurizr which is a set of tooling to help people create software architecture diagrams, essentially. So that's me.
 
Why is software architecture important for developers?

Stefan Tilkov: Very cool. So, as I'm a software architect myself, I will try to just ask questions but I'm very sure I'm going to have to agree or disagree, most likely agree with some of the things you say. Let's just start and discuss a few things. Maybe first of all the tools and the books, which we're gonna talk about as well, they all sort of seem to make a point of making their target audience developers. It's as if you want to draw attention to the fact that architecture matters to developers, and should matter to developers as well. Can you elaborate a bit on that? Why do you think that is or why do you think people could think that it's not important for developers to consider architecture?
 
Simon Brown: The whole software architecture for developers really came about when I worked for consulting companies. In order to scale and grow a consulting company, you need more teams to service more customers. For every extra team you need, you need more tech leads, more architects. So basically, a lot of this stuff came from me teaching our developers how to think about software architecture, to do software architecture, to communicate software architecture. When I was going through this myself earlier on in my career, I didn't really find these helpful in terms of, I'm a developer now and I've been thrown into an architecture role, what do I need to do?
 
There were lots of books out at the time. You've got all the SEIA and practice books and so on and so forth but I just found they were very researched-based and academic-focused and it didn't really give me, if you're an architect, this is the sort of stuff you should do. So that's really where my focus came from and hence the software architecture for developers theme.
 
To answer the same question from another angle, I guess, when the Agile Manifesto came around in the early 2000s, we saw lots of people jumping on that, which is great and there's a lot of benefits that came out of the agile movement. However, a lot of people started dropping some of the more design-focused, documentation-focused, architecture-focused techniques and practices and processes. I wanted to figure out how we get this stuff back into the way that teams work without seeming like that horrible dictator-style architect that people don't like. And also, I want to reintroduce some of the existing ways of working but with a little bit more of a developer focus so that the developers potentially pay more attention to them, if that makes sense. So that's really the kind of developer focus.
 
Is “Software Architect” a role or a list of tasks?

Stefan Tilkov: So do you think “software architect” should be a role or is it simply a set of tasks that people...that somebody just has to do?

Simon Brown: I think both, I guess. If you look back like 15, 20-plus years, every team would probably have an architect on the team who would do all of that stuff and they would rarely get involved in the code and they would tell people what to do and we learned that that's not a fantastic way to work.
 
Those tasks still need to be done but perhaps nowadays with our more modern agile approaches, they're much more collaborative. You know, trust is an inherent factor in many teams. Maybe we don't need that single person who's looking after all of those tasks and that's why I like to think about it as a role. So it is a role that the collective team needs to do. It doesn't need to be one person. It could be many people. That set of tasks does still need to be done in order to, you know, hopefully, get a better, more successful end result.
 
Stefan Tilkov: Yes. I think I completely agree with that assessment. I mean, after all, if you don't...you, sort of, have to do it because otherwise, what you end up with will be...will just be a matter of, you know, whatever happened to you, right. It'll be, sort of, accidental because some people made decisions and you just end up with some sort of architecture that may or may not be what you wanted.
 
Simon Brown: Yes. It's either the, kind of, accidental structure thing, so a big ball of mud or some of the quality attributes tends to get forgotten about because they, kind of, fall between the gaps between the people like performance and security and scaling. It's like, "Oh, I thought someone else is looking after that stuff but oh, no, it's our job, collectively."
 
Stefan Tilkov: Yes. I've also seen people build something that works perfectly well in some architectural dimension. The problem is just that that dimension was not one anybody really cared about. 
Nobody wanted that system to be that super scalable. You know, but it was a lot of fun to make it like that. I mean, can't say that I've seen too many systems that were too scalable. I mean, that would be a bit of an exaggeration as well. But right, of course, as you mentioned, the quality attributes are something that you need to take into account to make a decision, what actually matches those requirements.
 
Simon Brown: Yes.

How much architectural work needs to be done before you actually start coding?

Stefan Tilkov: But you have to know them first and then people often actually don't...yeah, completely agree. So, you mentioned the Agile Manifesto as, sort of, an influence, sort of something that let some people, I think we both agree, mistakenly to dismiss all of the architectural ideas and all of those things. But I think some of the reasons for that were that it was all very often at least associated with doing a lot of work upfront.
 
You know, like having somebody design the system, builds the architecture in the form of a lot of diagrams and prose and big documents and then just, hand it off to somebody else to actually build it according to those guidelines and decisions and rules that are in the big architectural master document. So, I think pretty obviously, that is not a good way to build things but maybe the other extreme isn't that great as well. So how much architectural work needs to be done before you actually start coding?
 
Simon Brown: There's a great quote by Dave Thomas. He says that "Big design up-front is dumb, and doing no design up front is even dumber." And it's that, kind of, flipflop from one extreme to the other which is exactly what I've seen teams do over the past, what, 20 years now. So, I completely agree. Doing too much kinda locks you down. It's too rigid. You spend lots of time getting there. You spend lots of time potentially solving problems you're never gonna have. Then you have to, kind of, order and make sure all of the people are doing all of the things according to the document you wrote four years ago, which, you know, and the world's moved on.
 
And I think a lot of people misinterpreted the Agile Manifesto. And because the Agile Manifesto doesn't explicitly talk about doing up-front design, a lot of people, I think, have interpreted that as the Agile Manifesto says don't do up-front design. If you read things like extreme programming and if you read some of the principles, it is easy to kinda get that view of what the Agile Manifesto is saying. But I don't think that's the case.
 
What I find amusing about all this is when I worked for consulting companies back in the early 2000s and the Agile Manifesto was coming out, I looked at it and I thought, "Well, that's kind of what we're doing anyway." You know, I was very hesitant in doing the big up-front design because I needed the...well, first of all, it's really boring. I did work on a few projects prior to that where we do like six months of just doing design and using rows and putting UML diagrams into rows. It was very interesting from a domain analysis perspective but we wrote zero code and I just got bored of doing that.
 
So that was never really my approach anyway. My approach was "Well, let's get the big building blocks in place. Let's understand the major driving factors, the major important quality attributes like security and performance, and so on. And then let's build a design around that and then we'll fill in the blanks as we go along." So when the Agile Manifesto came in, I was thinking, "Well, that's what I do anyway." So, from my perspective, nothing changed too much. But I guess depending on where you were coming from at the time, your perspective was very, very different and I think that's what led a lot of teams down the no design route.
 
Unfortunately, in some cases, fortunately, in others, of course, those same teams are now realizing that was potentially a bad idea and they're now starting to go back and think about, "Well, what sort of design should we do up-front? How much should we do and what, sort of, architecture process should we put around making sure people are doing the things we think they're doing to fit into the constraints of the environment and the guidelines and the principles and everything else?"
 
Stefan Tilkov: Yes. So basically, it seems the answer to that question is you should do just enough up-front design. Just the right amount. That's a very easy answer.
 
Simon Brown: Which sounds obvious, isn't it? But it's, like, super hard to quantify.
 
Stefan Tilkov: Yes. Indeed. But I think we agree on that as well. So, that was an interesting thing that you just mentioned, which is this impression that sometimes when you read a book or, you know, some sort of paper or some blog post or whatever, you look at it and say, "Well, so that all sounds totally obvious and I mean, that's what we're doing anyway so why is everybody making such a big fuss about the whole thing?" But I've come to think that, in some cases at least, is the sign that this is a very great contribution, a very valuable contribution because it actually articulates something that should be obvious and maybe is obvious to you as a reader but actually may not be.
 
So to be perfectly honest, I had some of those feelings when I first read your book, right, because I was like, "This is..." That's one of the reasons I said we'll probably agree, right, how...this all seems very reasonable. It seems so reasonable that I keep saying, "Well, yeah. Duh. I mean, sure. That's what you should be doing." But I still think there are excellent books and because they actually provide a lot of value to people who may not have that experience, who may not have arrived at those conclusions and they get it in the form that actually makes it tangible and gives them some actual guidelines of doing things. I think what I'm trying to say is that if you read a book or if you're looking at something and it seems kind of like what you're doing anyway, that's not a sufficient reason to dismiss it. It may be an excellent thing, just what you need to convince other people.
 
Simon Brown: Yes. And of course, there are lots of people now entering the industry and they didn't see the stuff that predated the Agile Manifesto. So they missed that whole journey and now they're just getting the end bit where it's, we move fast, we break things, we don't do design. And like, "Hang on a second. That's not what's happening here. We should maybe step back and plug some of the gaps that these people don't have in terms of knowledge and experience."

The importance of diagrams in software architecture

Stefan Tilkov: Yes. Good point. So, one of the things that you emphasize a lot is the role of visuals, right, the role of diagrams, visualizing architecture. So can you talk a little bit about that? Why is it not enough to just, you know, sketch something on a whiteboard somewhere and then wipe it away 30 seconds later?
 
Simon Brown: So that's funny. That is one of the big things that the Agile Manifesto and the agile movement has trended teams towards. It's the, "You don't need these big design documents, you don't need to do these big heavy up-front design processes and you don't need to use expensive tooling. Grab a few people, draw some sketches on a whiteboard, have that conversation, and then erase it." The emphasis here is the values in the conversation. And I completely agree, you know. If we've got a bunch of people around a whiteboard and we're talking about different ideas and different designs and different approaches and we're assessing tradeoffs and stuff, that's a super, super valuable conversation and we should definitely keep having those things. The problem I've seen is that once people erase these diagrams, a lot of that knowledge gets lost. Now sometimes people take a photo and they stick it on Confluence and that's all good but...
 
Stefan Tilkov: Nobody ever looks at that.
 
Simon Brown: Right. Nobody looks at it because nobody can find it, first of all, because the architect who drew it quit three years ago or something. If the diagram doesn't make sense from a visual perspective, it's very easy to interpret what you think the diagram means and that might be completely different from what everybody else thinks. So, I'm a fan of whiteboards and I definitely recommend teams use whiteboards for doing up-front design. I just want people to add a little bit more, and I have to be careful how I phrase this, formality and structure around what they're drawing because it's far too easy to draw two boxes on a whiteboard, stick an arrow between them and that could literally mean anything. I want the stuff that we're drawing to have a little bit more meaning.
 
Now, of course, you might ask, "Well, why don't we just use UML?" And that's a very good question. And up until, sort of, 2004, 2005, I was a big UML user. So all of the documentation I did, all the sketching I did was using UML. But it went out of fashion and people dropped it like a hot potato in, sort of, the mid-2000-ish to 2010 years and it's not really bounced back. 
When I go and see teams and I say  "What sort of notations are you using to draw your architecture?" They literally just say boxes and lines on a whiteboard. There's no mention of UML. Some of the people have now been through university and college and their apprenticeships. They're not being taught UML. So again, you have a whole bunch of people in the industry who have missed out on all that stuff and they just think, "Well, let's draw some random boxes and lines because that's what everybody else does."
 
And to get back to your question, I think, and I hope...I think visuals are super, super important. I think you can literally hang all of the other stuff related to the architecture role around a good set of visuals because that good set of visuals allows you to tell stories, it allows you to have design discussions, you can make design decisions, you can assess tradeoffs and it just opens up all of the information to a much, much wider audience. So that's why I place so much importance on the visuals.

Did remote work and the tools we are using add more structure?

Stefan Tilkov: So do you think, because everybody's now working remotely these days, do you think things have changed because tools are more important and the things that we create are more structured because the tools typically offer some structure as a default?
 
Simon Brown: I think, and especially if you look at remote working and especially with the whole pandemic thing, what teams have done...and I've definitely seen this. They've taken their whiteboards in the office because they're not allowed in the office anymore and they're using tools like Miro because they can basically fire these things up, you can get a bunch of people looking at them, you can all interact and collaborate at once. And Miro is a fantastic tool and I'll certainly use it myself for other things but it's not going to give you structure. 
So if you approach a whiteboard, it's not gonna provide you any assistance in drawing an architecture diagram. It's not gonna help you explain what types of abstractions you should be drawing and, you know, the semantics of the visual language you're using. Miro is the same. It's just a great way to draw boxes and arrows collaboratively. It's a collaborative online whiteboard.
 
I think we're missing a trick for tooling here. I think...and again, I have to be careful what I say here because it's very easy to interpret what I'm saying as, "We should go back to doing what we did 20 years ago with rows and have lots of rules and semantics and it was all very, very precise." And maybe that's too far. So maybe we need to reign that back a bit but have some tooling that actually provides some assistance. It's the same with, like, AutoCAD. Now if you want to sketch out a set of building blueprints, you don't fire Visio up. Visio's gonna offer you no assistance at all apart from you've got this box and this box and you can put them together and group them. You're gonna use some of that AutoCAD because it's going to provide you assistance and rules and different things like that. So yeah, I think there's still some more work to be done there.
 
Stefan Tilkov: Yes I think what people might be missing is that the assumption somehow seems to be that if you use something like UML or any sort of structured case tool, whatever, you know, whatever it happens to be, then, in the end, you might have to specify things at a level that is very close to programing, right. So people fear that they have to go into all of the details and provide all of the...fulfil all of the requirements for something that could then be automatically turned to code, which is not something that you have to do. I mean, you could possibly do that. Whether it's a good idea or not, probably beyond our scope today. But even though you could do that, you can just as well use a tool like that to model something at a very high level, right. Just draw the high-level structure of your system just with a little bit more meaning, more semantics as to this is what this kind of line means, right. If it's a dashed line, it means something different than a solid line because that's why we make it a dashed and not a solid line so...
 
Simon Brown: Right.
 
Stefan Tilkov: Whatever that...and you could invent your own notation...
 
Simon Brown: Yes totally.
 
Stefan Tilkov: ...and then stick to it. That would be perfectly fine. But you could also use one of the notations that's already there. For example, UML which, of course, gives you a ton of variation, lots of ways to customize it and because it's a super-powerful, super-customizable tool, may end up being super-complex and way too powerful for what you want to do, as usual. There are alternatives, which I'm sure we're gonna talk about very soon now so...
 
Simon Brown: Yes.

The C4Model 

Stefan Tilkov: Let's talk a bit about your efforts here. I think there are two things that we should talk about. One is C4 and one is Structurizr. Maybe we can start with the C4 model, and you can go into a bit more detail of what that is and how it differs from UML.
 
Simon Brown: The C4 model is essentially a formalization of how I've always drawn software architecture diagrams. So in that kind of post-UML phase where the organizations I was working for and with didn't want to use UML and so they've threw us back to Visio. I had a specific way that I do software architecture diagrams. So if I'm building a software system, I want a box in the middle of my diagram saying, "This is the thing I'm building." I want to list out all the different types of users, the roles, the actors, the personas, and then I want to also show my key system dependencies because, of course, as you well know, anywhere you've got a system dependency, there's some sort of interface and there's always some sort of risk associated with doing that.
 
That was always really my starting point for drawing out an architecture. Then I wanted to zoom into the system I was building and show deployable, runnable things. Like, if we were building a web application talking to a database, I would literally draw two boxes. Here's the web application and here's the database with an arrow between them. And again, this is really reflecting how I thought about the architecture from a developer's perspective, you know, as someone who ends up coding on those sorts of projects.
 
When I started teaching people how to do software architecture, I was quite focused on getting people to do the stuff we talked about before. So understanding architectural principles and guidelines and constraints and quality attributes. I had a little case study in my workshop where people would group together.They'd go and do a small round of up-front design for like an hour, and the output was one or more diagrams to describe their solution, essentially. After doing that a bunch of times, I realized that I couldn't understand any of the diagrams and neither could anybody else in the workshop. So now I thought to myself, "Well, I know how I do this. Why don't I figure out how to teach that to other people?" Because I just naively thought that everybody else did the same thing but it turns out they don't.
 
So that's where the C4 model essentially came from. It was formalized in the latter half of like 2005 up to 2010, something like that. And the C4 model is a hierarchical set of diagrams to describe software architecture. C4 stands for context, containers, components and code. So the context is a system context diagram, and that's basically what I described already. It's a very high-level diagram. It's a single box in the middle representing the system you are building. So maybe like an internet banking system. It's got the different types of users and actors and roles with personas around it with arrows, you know, using the system. And then a set of other boxes representing your system dependencies.
 
Then you zoom into the system boundary and you show what I'm calling containers, and I'll come back to that in a second because it's a little bit controversial. So I call these things containers, but basically, they are deployable and runnable applications and data stores. If you're building, you know, an angular single-page app that's sending JSON across the internet to a backend Ruby on Rails app which is sticking stuff in a MySQL database, you draw those three boxes and the arrows between them. So again, it's really reflective of the realities.
 
If you want to, you can zoom into an individual application or data store and show components inside them. What do I mean by components? For me, it's just a grouping of stuff. Usually, you know, a grouping of stuff, nice, well-defined interface. The components often or usually relate to how you are structuring your code from a high level. So if you think about your codebase as a set of components in a layered architecture, then your component diagram essentially represents boxes in layers. If you're doing ports and adapters or hexagonal architectures or package by feature, then that's what your component diagram is essentially showing you. And then if you want to get really into detail, you can zoom into an individual component to show the code inside it.
 
So there's a few things to unpack here, I guess. Number one, why did I choose the term container? So, I think I got there before Docker. That doesn't make this right, but I tried to find a term that didn't have many associations, and I obviously failed very badly. So I didn't want to use the word process because that's not what I was trying to show. I didn't want to use the word application because that's not what I wanted to show. At the time, I was big into JHEE, and we talked about server containers and EJB containers. I just liked that container, kinda, metaphor. It's like, "Here's the thing that runs and stuff goes inside it." So that's why I chose the term containers.
 
And although the C4 model has the number four in the name, I definitely don't recommend doing all four levels. So for most uses and most teams, the top two levels are more than sufficient, and if you want to get more detailed, you can. Then you get into a whole question of should you start automating diagram generation and so on and so forth but again. That's a bit abstract for this discussion. So that's the C4 model in a nutshell. It's a hierarchical set of diagrams to describe software architecture at different levels of abstraction, and those different levels of abstraction allow you to tell different stories to different audiences.
 
The difference between UMLs and the C4Model

Stefan Tilkov: Okay. So my understanding… and I'll be interested to see what you think of that. My understanding is that the major difference between that and what UML does, for example, is that UML is far more generic, right. It's got all of those things somehow. You can absolutely 100 percent use UML to do the exact same thing. It just doesn't recommend anything, right. It just gives you tons of options, and you have to decide what to do with them. So you could use a component diagram and some sort of package diagram and the packages have sub-packages and you could drill down all the same… in the same way finally ending at classes or whatever it is.
 
And I've seen you actually recommend combining the C4 model with other diagram types that are in UML like a sequence diagram or a collaboration diagram. So it could totally do that. What I do see as the major thing that people find attractive, that people find useful beyond the UML part, is that you actually made some decisions, not all of them but some decisions to say, "This is the useful level," right? Just not any arbitrary number, it's four. Not any level, it's these. Right?
 
Simon Brown: Yes
 
Stefan Tilkov: This may really be a stretch but I wanted to run this analogy by you. It reminded me, weirdly enough, of something Eric Evans did in the DDD book because even before the DDD book… and that obviously was also one of those, "Oh, I'm doing that already while I'm reading this book," for me. He sort of proposed a number of, what in UML I would call stereotypes, right. Like  these are the kinds of things beyond just classes, right. We have value objects and we have entities and we have services and we have those things. And he sort of made a very explicit choice to include these, whatever, 10 things.
 
It's not a real difference from just saying you have stereotypes and you can actually customize the generic UML class diagram or the class concept to mean something more specific but still, it's immensely useful because it gives people more to hang onto. It just gives them a starting point as opposed to the super generic thing that then somebody else would have to customize to actually become useful. Is that a fair analogy or am I totally off?
 
Simon Brown: No, that's a completely fair analogy. I was just gonna ask you do you remember Peter Coad's "UML Modeling in Color," I think it was called?
 
Stefan Tilkov: Yes.
 
Simon Brown: It was the same thing. It's like you have these four different types of classes, and you make them different colors. So what's really interesting is the C4 model does not prescribe a notation. There is no C4 model notation, and you can do whatever you want and you can upload whatever visual semantics to whatever notation you choose. You know, different shapes and colors and all that sort of thing. Something I always do in my workshops is I say to teams, "You could use UML to do these diagrams." You're exactly right. You come up with a set of conventions and rules and maybe you use a use case diagram for system context diagram or maybe you have a component diagram and you apply appropriate stereotyping and that sort of thing.
 
I do offer this as a thing teams can do, and no one does it. And I still find that surprising. I think you're right. When I introduce the C4 model, I often get a lot of skepticism because… and again, I kind of have to be careful how I phrase things initially because it tends to put a blocker up immediately. If I say, "I'm gonna teach you a diagramming technique and it's a framework and it has a bunch of rules and it'll make drawing diagrams really easy," everyone will instantly switch off. So that's not the approach I can go in with.
 
If we have the discussion after the workshop and I say, "So, you've gone through this, you've created a bunch of useful diagrams. I can see you really like them. What feedback do you have? What do you think is the selling point of this?" A lot of the people actually say, "Well, you've given us a framework to work in." And it's the same thing. It's like, I've given them something to hand their ideas off, I've taken away a lot of the silly decisions that really don't matter all too much. It's just a way to draw a bunch of pictures. We know what the pictures are, and we can move on and we can get focused on something more important.
 
Stefan Tilkov: That's awesome. I think that the key point here is there are tons of places where your creativity is way more useful than in the kind of lines or the way you draw a box, right. I mean, that's...
 
Simon Brown: Like, who cares?
 
Stefan Tilkov: You have a choice with your architecture diagram notation, but no user is gonna be happier because you decided to use color this way. Just getting it out of the way is a very useful thing there.
 
Simon Brown: Yes
 
Should UMLS be part of a CS education?

Stefan Tilkov: Ok. Very good. So, when you think about UMLs, should we still be learning it and teaching it? Should it be part of the CS education?
 
Simon Brown: I'm going to say yes, actually. I think it's very useful. So again, if you go back to the early UML 1.0, 1.1, which was '98-ish, maybe something around that, sort of, time scale...
 
Stefan Tilkov: The '90s, yeah.
 
Simon Brown: Yes. You can actually still find some videos of Grady Booch and the others teaching UML and I think the best version of UML was actually those early versions because they were nice and lightweight.
 
Stefan Tilkov: They were simple.
 
Simon Brown: There was a smaller number of diagrams. Right, it was much, much simpler. And I've seen this complaint lots of times that over the years the vendors have all got involved, they've all wanted their specific features for their specific tooling, they're all focusing on UML and defining complete architectures and you magically press a button and all your code pops out. The whole UML thing has become sidetracked by vendors, essentially.
 
I think if you look at the core of UML, there's a lot of really good stuff in there. I don't like the fact that you have to read 750 pages to understand the entirety of it. The biggest thing I don't like about UML, aside from some tooling which is awful… different story. But the biggest thing I don't like about UML is it doesn't help you. And this is exactly what you were saying earlier. If you fire up a UML tool and you say, "Right, I want to describe an architecture," it gives you no assistance. Furthermore, there are no good examples or case studies about if you have a modern Mac services-based application, think about using these sorts of UML diagrams in this sort of way to describe what it is you're actually building and make it reflect reality and reflect the code and all that sort of stuff.
 
Those are the main problems with UML but having said all that, I still think it's a useful thing to teach. The C4 model, it doesn't cover state diagrams, it doesn't cover activity diagrams, it doesn't cover business process diagrams or entity relationship diagrams. So even if you use C4 model diagrams I still think there should be supplemented where necessary with a whole bunch of other stuff from UML, from ArchiMate, from, you know, good old-fashioned entity relationship diagrams. So I definitely think we should still be teaching it, but maybe with the emphasis that it's a tool in a toolbox. There's some useful stuff and there's some maybe less useful stuff.
 
Stefan Tilkov: It's almost a little annoying how much we agree, right. Maybe we have to talk about microservices at some point to find something we disagree with.
 
Simon Brown: The most boring discussion is when people agree.
 
Stefan Tilkov: No, I totally agree with everything you said. I think it's useful, I think it's way too big and way too complicated. I think the mere fact that at least with a lot of people, you can draw a diagram in UML notation, and a significant number of people will understand the semantics of what you just drew. I mean, that's an extremely useful thing, right.
 
Simon Brown: In theory.
 
Stefan Tilkov: It's kind of obvious, right? It's having a common language for those things and there are no points to be gained by, having a different one than all the others because your class diagram is super special or your entity relationship diagram, which is typically shown as a class diagram these days so...
 
Simon Brown: Yes
 
Stefan Tilkov: Yes.
 
Simon Brown: Just to actually pick up on something you said there, one of my recommendations is even if people are using UML, they should still stick a diagram key, a legend, to explain their notation because not everybody knows it. That's one of the biggest things. Once they see that complicated set of boxes and lines they've never seen before, they're like, "That's too much for me."
 
Stefan Tilkov: Yes, very good point. I also think that even within those diagram types, there are certain things that you might not want to use for certain audiences, right, like using inheritance in a diagram intended to communicate with a businessperson is not gonna help you in any way, right. Maybe it's a refinement if you wanna do it at some later point in time but it's not gonna ease things at that stage. Neither are UML stereotypes or, you know, the types of attributes or whatever. 

How do you keep diagrams in sync with your code?

Stefan Tilkov: So, one of the things that comes up I think quite often is the question of how do you keep documentation in general and diagrams just specifically in sync with the rest, with the actual code because the code is obviously what matters and there's nobody… nobody gains anything if you have a diagram that's out of sync with actual reality. What are your strategies there?
 
Simon Brown: You've got two basic options and, in many cases, option one is the most simple. And unfortunately, at the moment, the most effective. So option one is just update it. So if you've got a definition for your tasks or your work items, you add a line at the bottom and it says, "Have you updated the diagrams and documentation given this, hopefully, small change that you've made to the code base?" And that's often the easiest way. It's just a process thing and it's done and we can forget about it.
 
Option two is much more complicated and that's really, "Well, let's autogenerate the diagrams and the documentation of the thing we're actually building." And that thing we're building could be the code itself. We could auto generate diagrams off the code or we could perhaps auto generate diagrams of built scripts or infrastructure provisioning scripts or maybe the live infrastructure or maybe things like distributed logging and tracing. So you've got a bunch of different inputs you can use to potentially automate and auto generated diagrams. However...and this is where things start to get a little bit complicated. And I'm sure you've seen this yourself. If you open up an ID with like a million lines of code and you ask it to draw you a picture, what do you get? Like, just an utter mess.
 
Stefan Tilkov: Things like crossing lines and...
 
Simon Brown: Yes. It is not because your code's a mess, hopefully. It's because it's trying to show you too much. It's trying to show you exactly what the code looks like. It's reflecting that low level of detail. That's not useful to us as humans. We need to chunk it up and zoom out, which is where the C4 model comes into play again. You often get the same thing if you saw autogenerating for built scripts and running infrastructure as well because if you've got like 100 versions of a microservice running, do you want to show 100 things, or do you want to show 1 thing with some variability somewhere else?
 
So, the whole autogeneration thing is a bit complicated and it's a bit tricky at the moment. Also, a typical codebase doesn't tell you the whole picture. So if you think about the system context diagram I briefly outlined earlier, you've got a box in the middle representing the system, different users, different system dependencies. It's really hard to generate that high-level diagram just from using the code as an input, as a source. So that's some of the real-world challenges we face here. There's not enough metadata in most code bases to generate high-level pictures and if you generate the low-level pictures from codebases, you often get too much and there's often no easy way to get that happy medium. So that's why option one is often the easiest, unfortunately.
 
Stefan Tilkov: Yes. I'm old enough, as you probably are, to remember things like Together, it started out Together, C++, Together, Java, whatever. The Together case tool that simply you can't really say reverse engineered… simply showed you your code as a UML.
 
Simon Brown: It was a roundtrip, wasn't it?
 
Stefan Tilkov: Just complete roundtrip engineering where you could actually edit the code within the diagram. You could switch… you could seamlessly switch between the IDE because, essentially, the case was your IDE. I never found that an appealing thing because it didn't give me the abstraction that I want from a model, right. I want the model to focus on one aspect. Like, for example, the structure that you mentioned. If I wanted to focus on all of the details, I would look at the code and not at a high-level diagram, so...
 
Simon Brown: Yeah, me too.
 
Stefan Tilkov: Another, I think, extremely important point that you made that I also want to highlight, which is the one that the code, while being super important, is not everything, especially not in modern architectures, right. Maybe, I highly doubt it even then, but maybe back then like 20, 30 years ago when you wrote a program that essentially was a standalone thing that you ran on the command line and then produced whatever, a file, took a file as an input, produced another file, then maybe the whole truth was within the code of that particular program.
 
But these days, everything is a complicated collection of independent, deployable units or containers in your terminology if remembered correctly. So all of those things communicate and the communication paths are sometimes only discoverable at runtime. They're not even in any configuration file or in anything that resembles code, right. It's really something you could only discover if you could look into the minds of the architects or actually… or the coders, developers, or actually observe or surveil the system while it runs, so...
 
Simon Brown: Yes.
 
How can you visualize software diagrams and documentation?

Stefan Tilkov: That is definitely a very complicated thing. Have you, by the way, found a solution to I think a related problem, even if you can figure out, like, say, dependencies between artifacts of some kind between deployable, for example, once you visualize them using something like GraphThis or any sort of thing, I think while the quality has gotten better in recent years, it's never as perfect as something that you would have drawn yourself, right. If you can actually realign the boxes and move this line a little bit there and this box a bit over here then it actually looks better. The problem, of course, is it's lost once you regenerate the whole thing where actually you have to do that over and over again. Has anybody yet come up with a solution that allows you to, you know, apply the visual changes like a DIF to the auto generated graphic? Am I making any sense? Do you have any idea what I mean?
 
Simon Brown: Yes. So I must say I'm not a huge fan of the auto-layout algorithms like you get in GraphThis. I always find they put things in the wrong places and when I'm telling a story, if I'm doing a presentation or something, I want to point things out or I want to group things visually because they kind of belong together. They might be the same type but from a kind of nodes and edges graph perspective, you know, you've got your typical all dependencies flow downwards, with things like GraphThis and PlantUML and they give you this weird layout.
 
Something I did a while ago was I started quoting some tooling called Structurizr, and I wanted to build something that would let people draw diagrams easily and, again, would take some control away from them. Does that make sense? No. To take some freedom away from them in terms of the notation. So, kinda, a fixed notation. But I still wanted the ability to move boxes around myself. So as part of the Structurizr tooling, you can upload a new definition of your model and the views in the model and the Structurizr tooling will attempt… and it's not perfect by any means but it will attempt to retain the existing layout. So I'm trying to do a blended approach there.
 
Stefan Tilkov: That's basically what I was asking for. So that sounds very interesting. So can you tell us a little bit more about the Structurizr? Just maybe a brief intro?
 
Simon Brown: So when I was doing my workshops on the C4 model, up until about five years ago, people would always ask me, "What tooling do you recommend?" My answer was always, "Just use Visio." You have no idea how irritating and frustrating that is. So I figured, "Well, I should try and do something. If I'm promoting this way of drawing diagrams, I should try and build some tooling myself." I sat down and I started to put together… and this sounds horrible, and it was. I started to put together an HTML web-based modeling tool specifically targeted around the C4 model, and it was horrible. It was the worst UX you've experienced in your life.
 
But the interesting thing about that was the stuff behind it, the actual framework and code I'd written, was a really nice way to succinctly define a model and different views onto that model, and that was essentially a set of Java classes.There were a set of Java classes sitting behind this web application representing people and software systems and containers and components. 
I figured out, well, let's ditch the UI. Let's only have the UI for drawing the diagrams and let's allow people to describe their architecture using code. So you basically create a bunch of objects in memory, wind them together with a nice little API and that would create you, essentially, a directed graph. Once you have that directed graph, you can export it to different formats and visualize in different ways. And that's essentially where the Structurizr tooling came from.
 
So that was about five years ago. There's a whole bunch of different ways you can use the tooling and there's a community of different tools that have, kind of, popped up around it. So my original version of tooling was you write some Java code, you get some diagrams. Now there are libraries for all sorts of different languages that people have written and they're open-sourced. When we were locked down last April, I put together… so if you're familiar with something like PlantUML where you write text and get diagrams, I created something I call the Structurizr DSL, domain-specific language, and it allows you to define a model and a bunch of views as a single DSL file.
 
Also, whilst we were in lockdown and I wasn't doing very much traveling, I came up with a bunch of open-source tooling and there's something called the Structurizr CLI. So what you can do is you can define a C4 model, so to describe your architecture. And you can describe a set of views in that single DSL file. Then using the CLI, you can export it to my Structurizr tooling, which is available at structurizer.com, or you can export the views in that DSL file to PlantUML or to Mermaid or to WebSequenceDiagrams. So what it's become now is a way to describe an architecture using the hierarchical diagrams and the hierarchical viewpoints and stuff but with independence in the way you actually visualize that model. So that's kinda what it is today.
 
Resources for developers getting into architectural work

Stefan Tilkov: Very cool. Okay. So before we wrap up, one last question I have is obviously, we're going to point people to your books and to Structurizr, to your website, which has lots of resources. Are there any other resources that you think are useful for developers getting into architectural work?
 
Simon Brown: Developers getting into architecture work? There's a bunch of really good books that have come out recently. So Neil Ford and Mark Richards have a book. And the name completely escapes me.
 
Stefan Tilkov: I think it's "Fundamentals of Software Architecture."
 
Simon Brown: Yes, "Fundamentals of Software Architecture," correct, yeah. I can visualize it with the picture on the front. So yeah. That's a very good book for people looking to get into architecture. Greg Hope has got a book out called "The Software Architect Elevator," and that's a really interesting book because it talks about the software architecture role not just from a technical perspective but in terms of what that role means to the entire organization and it focuses a bit more on soft skills and presentation skills and influence and that sort of thing. So that's another really good resource I'd point people to. Plus, you've got Michael Keeling's "Design It." You've got George Fairbanks' "Just Enough Software Architecture," Eoin Woods, Nick Rozanski's book, "Software Systems Architecture." There's lots of really good stuff out there, kind of, focused now at software developers.
 
Stefan Tilkov: Excellent. Well, I'll definitely put them all in the show notes and then our listeners can definitely check them out. Ok. So, thank you very much for all your time, Simon. It was an awesome conversation. I really, really enjoyed it. Thanks for being with me, thanks for being with us, and enjoy the rest of your day.
 
Simon Brown: You too. Thank you.