Crafting Code Podcast

[00:00:00] Allan Stewart: Welcome to Episode 3 of the Crafting Code Podcast, where we discuss the importance of doing the right thing at the right time and with the right tools. I'm Allan Stewart, a software architect, and lately I've been thinking about the problem of batch sizes and Brandon Sanderson novels.

[00:00:16] Dave Adsit: I'm Dave Adsit, CTO, and lately I've been thinking about coupling, cohesion, flow of value, and low-code solutions across a company.

[00:00:27] Matt Baker: I'm Matt Baker. I'm pretty sure I work in software. Some days I'm not sure. Lately, I've been thinking about the Kafka Wire protocol and using fast feedback loops to engineer a game I've been playing called Rocket League.

[00:00:40] Allan Stewart: So our title, episode title for today, is Two Conversations Pass in the Night. We'll be talking about communication and how communication relates to crafting code. As we look at the software. Craftsmanship Manifesto, it definitely talks about some things that require communication. Well-crafted software, right? The code itself can communicate something. We want to work in a community of professionals and have productive partnerships. All of these things require some communication, but it's not always as simple as we wish it were, hence the title. So we're going to kick things off by talking about writing code for humans. So if we... If we want to write some code, a lot of the time, especially when we're first learning how to code, it's all about syntax. It's all about getting the computer to do what we want. And so we tend to think about code as communicating with the machine, getting the machine to do what we want it to do. But why would we want to communicate with humans through code?

[00:01:49] Matt Baker: Yeah, it's an interesting question. My mind immediately went to a place that's not necessary. Not necessarily the question you were asking, but... I'm thinking about early on when I was writing software. One of the most important things to me was terse syntax. The shorter I could make something or the more compressed I could make something, the better. So as you started talking about writing code for humans, now in my career, I look at things like terse syntaxes. Definitely not optimal.

[00:02:28] Dave Adsit: Yeah, a lot of the platitudes that we've heard or the quips about writing code kind of flash through my head. But I think at the end of the day, I'm tired of producing legacy code. I want people who come behind me to not resent me for the things I did to their code base. So... I would like it if they could see the code and understand, at the very least, understand the intent, even if the code didn't do what it was supposed to do. So... I think that's the big thing for me these days when it comes to writing code for humans.

[00:03:15] Allan Stewart: One of my favorite quotes from Martin Fowler says, Any fool can write code that a computer can understand. Good programmers write code that humans can understand. That... Kind of at the turning point of my career, right around the time when I was first learning about what it meant to be professional and write good code, write clean code, I came across this quote in his refactoring book. And it's really stuck with me because code tends to get read a lot more than you write it the first time. When you're writing it, you're in one frame of mind. But when you read it, you're in a different frame of mind. So even if the only other human that reads it is yourself down the road, it can make a huge difference if you have communicated your ideas clearly. And if you're working in a team, then it's all the more important that they understand what it was that your code was doing.

[00:04:17] Matt Baker: I think when you talk about communicating clearly or writing code that humans can understand, the word that comes to mind for me is plain. So the word plain is very good for me. So the word plain is very good for me. mother object factory that produces like a writer reader streamer that you know and it's a few underlines of code and then at year 10 they're back to the console.log hello world and i i think we all go through that progression and right now for me i'm just at plane like how can i write the simplest plainest code possible you know and i've started to really value that more than i value some like i was saying terse syntax or maybe some kung fu code that you know takes you a while

[00:05:23] Dave Adsit: to untangle but is intellectually impressive yeah i really appreciate that i think that one of the places where i've tripped myself and others up many times in the past is by trying to use clever ways of communicating inside of a code base instead of i don't even know examples are hard to come by these days because i i've completely given up the habit but you know character because that's what i thought of in the moment or this part of the code kind of reminds me of that time i was hiking and so i'm going to name it after the hike that i was on none of that communicates to anyone else including me a month later and so now i'm just like var board equals new board not because i'm bored but game boards come into to a lot of my coding these days.

[00:06:25] Matt Baker: Well, I think you could say also var, you know, file reader equals new reader or var like HTTP response from payment API. Like these are-

[00:06:39] Dave Adsit: Those are names that I would understand a week later. That's right, yeah.

[00:06:43] Matt Baker: And I also think that they are names that are constantly abbreviated. Like I don't know exactly how to categorize those, but depending on the code base you're looking in, you might see like one or two letter variables holding those or like R for response. And, you know, going back to that plane thing, I definitely appreciate a code base where they don't care about being a little verbose if it means that they can communicate better.

[00:07:06] Dave Adsit: Well, it all gets compiled out anyway, right? Like the computer doesn't care what you name the variables anymore. And if you're using any kind of modern tooling, the tooling is gonna help you type the long variable name in the context where it's relevant.

[00:07:22] Allan Stewart: And again, even if you do have to spend some extra keystrokes because you added some additional letters, some additional context, it's gonna be worth it because you're gonna read that a lot more. And the more that your tooling helps you, the more that you can focus in on what is it that I'm trying to accomplish with this code rather than some kind of Hungarian notation of the types of all of my variables and how many, you know, bytes of memory they've all allocated. And all this other stuff, which was important at one time, especially when we didn't have the tooling. But with what we have now, we can really focus on the domain of the problem rather than anything else. And that's hard enough, right? There's the famous Phil Carlton quote, there are only two hard things in computer science, cache and validation and naming things. And I found that to be so true. Like there'll be times where I'm just like, okay, here's, I'm writing this code and I know what I want it to do, but I don't know what it's called. What even is this thing that I'm creating? What do you do in those moments? What do you do? Oh, that's a good question. Cause I was gonna say, you know, why is it, why is it so hard sometimes to name things? But it's kind of a fundamental thing. And so what I do is give it the best name that I can in the moment and move on and hope that before I'm done, because done for me includes some measure of refactoring and going back and making sure that it works well, that I will discover what it was that I was naming in the first place. One of my coworkers put me onto a great article where they talk about naming things, applesauce or other similarly, obviously wrong names. As long as you're not working for Del Monte, then it's probably not actually a variable for actual applesauce. And that's a clue to other people. Okay. This is wrong. And broken. Please figure out what this really is and fix it.

[00:09:25] Dave Adsit: This code is not yet done.

[00:09:28] Matt Baker: I I've even named variables. Like I seriously can't be bothered right now. Like, I mean, just like, I can't think about this. I'll come back. But for the same reason, like that, that'll catch my eye at some point.

[00:09:40] Dave Adsit: Yeah. In the way that I or a or R won't. Exactly. You know, you put a single character as the variable name, and you might think that you meant it.

[00:09:53] Allan Stewart: Or you just gloss over it, right? Because it was just that one character. And I, it was probably like an index or something. X, it was probably just like, you know, a Lambda expression. And who even cares? Until it turns out that you did actually care.

[00:10:11] Matt Baker: Yeah. I'm to the point now where I, I hesitate to even use I, the variable name I in for loops. Where I think if there's one place, where I can say, where the single character aside is the single character aside, where the single character aside is the single character aside, where the single character aside is the single character aside,

[00:10:36] Dave Adsit: where the single character aside is the single character aside, where the single character aside is the single character aside, characters from the way the problem is written by the experts. And a lot of times it's very simplified. On the other hand, I don't know how to type a theta on my standard ASCII keyboard. So sometimes I don't do that either. Sometimes I'll expand those out. I'm like, but what does this character mean? And use that instead, because that helps me remember what they're talking about when they're doing the fancy math or whatever. What's that one? Is it prologue?

[00:11:23] Matt Baker: The programming language that has sort of cryptic syntax? That's what I'm thinking about. Prologue theorems expressed in a very interesting language. Yeah, for sure. I guess that was actually one of

[00:11:37] Dave Adsit: the things that was considered an advantage of early Scala is that you could use Unicode characters to represent. Functions in the code. And then later people were like, yeah, but don't. We tried it and we could never reproduce or read the code that we'd written.

[00:12:02] Matt Baker: It's just sort of a, it's a one and done. It's like immutable coding. Like you write it one time. If you need it again, you have to write it again.

[00:12:11] Dave Adsit: That seems fair.

[00:12:13] Allan Stewart: Going back to this idea that naming things is hard. I think part of it is because we're trying to figure out what is going on in the code, what we're trying to accomplish. Sometimes we're not as clear with the domain as we should be, but sometimes it's just, there's these lies that creep in and they're unintentional. We get in there and we say, oh yeah, this is account ID or user ID. And we didn't realize until later that it mattered a lot, whether it was, what kind of a user, was it your customer? Was it your internal admin? Was it somebody else completely? And as we start figuring out what these things are, we get rid of the lies. Another one of the really big lies, I think are side effects. We get in there and these are lies that the code tells us, because when you're in the code, you're writing that function. You can plainly see that it writes to the database. But then you go step out. You're outside that class and you're somewhere else in the code. And it says, you know, calculate foo. And you're like, oh, great. I'm going to calculate foo. Never realizing that it's also saving that to the database.

[00:13:27] Dave Adsit: And emailing a copy to your accountant.

[00:13:32] Allan Stewart: So this takes us to kind of a related idea that we can just touch on for a minute. Clean code. One of the concepts of writing clean code is that you're creating, you know, very. Legible, readable, understandable code. So I'd like to ask the two of you, what, what does that mean to you? Like in practical terms, if you're going to sit down and write some code, or if you're thrown into a code base that you haven't seen before, how do you tell what does, what does it mean to you? Whether that code is clean or not clean.

[00:14:08] Matt Baker: I think there are a large list of tactics that you can employ. And their. Footprints will be all over a code base that I would call clean. Some examples that come to mind may be short. Functions. Classes that try and do one thing. You know, we could go on and on, I guess, about all the tactics, but the way. Lately I've been thinking about it. I'm trying to think about it as simple as. A conversation. My communication is only as good as you understand me. So if I say something and you don't understand. Regardless of what you're saying. I'm trying to think about it. Similarly, if someone can't understand my code, I would not call it clean code. Regardless of how perfect it is. If it doesn't communicate the idea. Then you fail to do one of the things you were trying to do. So, you know, as, as of late, I've been trying to look at it as well. Does. Can someone read this and understand my intent? And if so, I know that's clean code.

[00:15:08] Dave Adsit: I think for me, my favorite definition of clean code comes right out of the book of the same name. Which is the code pretty much does what you expect. So you read it. And then you read it deeper and you read it deeper and you're like, oh yeah, it, it did what it said all along. To me, that's, that's clean code. There are some other things that I look for. I really like the idea that. If you have clean code. When you. Decide to. Improve it and you start applying your refactorings. You pretty much end up back where you started. You had an idea of how to improve it, but then you went kind of around in a big circle. And now the code is the same. But slightly different. And you are different. In that you understand why. It was the way it was. To begin with.

[00:16:09] Matt Baker: I love that. I love that. What goes through my mind is your, your relationship with the coach.

[00:16:34] Dave Adsit: have introduced problems. But now I understand why it is, and so I just move on. Yeah, I really like

[00:16:42] Allan Stewart: finding those code bases where you have that consistency, kind of that elegant nature of the code where it is what it says on the label. It does exactly what you expect it to, and when you need to work in that code, you're able to go and make changes with relative ease. You can understand what it's doing. You can understand the gotchas. There isn't this interconnected, you know, I often think about it like this spider web that goes throughout the code, and if you pull on one little part of it, then it causes a ripple effect way off into some other part of the code. And whenever that happens, you know, that level of coupling, it's just a nightmare, really hard to work with, and you get afraid of changing anything. And clean code is easy to change. So I suppose that, you know, there's probably something about testing in there, too, because testing is definitely an enabler for changing code, for building confidence and whatnot.

[00:17:44] Dave Adsit: That makes me think testing is a skill, and coding is a skill. And one of the things that you said, Matt, is that when someone else looks at the code, it communicates to them effectively. Is it reasonable to think that there are different skill levels of code base? Maybe this code base is too complex for your current skill level. This is a black diamond skill code base, and you need to go ski back over here on the, what is it, a blue circle or something. You need to go back to the beginner slopes, because this code base is too hard for what you can do now. Is that a sign of a failure of the developer to write the code base? Or is that a sign that the previous developer failed to simplify the code base sufficiently

[00:18:40] Matt Baker: that the new person could understand it? No, it probably just depends. My mind goes to, I'm taking the model you're presenting and applying it to books. Let's say literature. If you're reading a really advanced book on some topic, and you've never studied it before, so you don't understand it, I don't think it would be fair to say that you're not a good to say that the book was bad at communicating. I think maybe, you know, it could also be fair to say that you just you don't speak the language, so you don't understand what it's telling you. So I think it's a fair point, Dave. There's this, like, you have to be this tall to ride element to it where someone might not understand a code base. I'm reaching for a concrete example. One of the first ones I go to is something like a bit mask. I don't think that, you know, a novice engineer is going to be able to understand why your what a bit mask is and how it's serving a particular code base or at least that's been my experience and I was one of those people and so that's an example in my mind where a bit mask could be a great expression of the problem domain but it is a, you know, it's harder to understand than declaring a string and it could be something else. something that someone might not understand, I don't think it would be fair to say that that

[00:19:59] Dave Adsit: code wasn't clean. I think the same could be said for certain patterns and practices, you know, depending on whether you consider dependency injection, a pattern or a practice, test driven development is definitely a practice that we apply, which has its own collections of patterns. And so if you don't understand the tests and you don't understand the dependency management structure, that code is going to be super foreign to your current level of understanding. But that doesn't mean that it isn't good or clean code. Yeah, it makes me think that there's

[00:20:32] Allan Stewart: probably often a happy middle ground for most applications. You know, there's going to be some parts of the domain that are more tricky, or there's going to be some parts of the code base, just some architectural decisions that were made, like this is how we do the dependency injection, or we always put our tests over here, just even certain patterns, like, oh, we use, workflows and repositories. And in this part of the code, we use a strategy pattern. And I think if you do a good job of communicating that, it can be kind of like those signs on your ski slope there, Dave, where you say, yeah, this part of the code base is black diamond. So we're putting up a big sign and telling you, beware. Here there be dragons. This is the place to be careful. But I think it's more fair to say that most of the time, software projects are more like the entire ski resort than a single run. And when you get there, you know, maybe even if you're an experienced skier, maybe it's best that you warm up a little bit on the slopes. Maybe don't tackle the quadruple black diamond, whatever. I don't ski clearly. Difficult slope. Yeah. You know, the ones with the slaloms and the jump that they do at the Olympics. Maybe that's not where you should start. Even as an expert skier, when you're first coming to the resort, and if you're very first coming to a code base, the code base might be clean. And one of the ways you can tell is you can say, okay, this is where I can warm up. These are the signposts that let me know what's up in the

[00:22:10] Dave Adsit: different parts of the code base. I actually worked in a code base that had comments at the top of some files that said something to the effect of not a drop code, which told me two things or maybe more. First, this code was important enough that you should never try to work on it when you had been drinking, which told me that one of my coworkers sometimes worked on the code while he was drinking, which was in and of itself interesting. So, yeah, I've actually seen that in practice. I think the code that was specifically not a drop code was all around payment collection and processing, which made me feel good about the code base. good because I didn't want any of that code to be intoxicated. You know, I'm thinking of the

[00:23:03] Matt Baker: Ballmer curve. I think there's also an aspect of observing the, I'm going to say the culture in the code. We talked about testing. I think a code base, one of the things that we'll have is a, you know, a statement on whether or not it's been written using TDD. I think you can see that in the testability of components. And I believe that if you've worked in a code base that wasn't written with TDD and you've tried, you've experienced how hard that is. And if you've had a code base that's TDD and had someone write code in it, not doing TDD, that to me feels like a, going back to the skiing metaphor, you remember that game on the old Windows PCs, the Abominable Snowman, that would be chasing the skier. I feel like the person that goes into a TDD code base and doesn't answer. So if you're not sure if TDD is that snowman, but I just, let's just keep the ski metaphor going, I guess. No, but what I want to say is sometimes a code base and the way it is written should change the way you might approach a problem in cases like with TDD. If you don't do TDD, but the code base does, you should do TDD. Similarly, if the code has a comment above every the file, maybe you should consider including that comment for the file, even if you're vehemently anti-comments, because there's something to be said for consistency when we talk about clean code.

[00:24:32] Dave Adsit: It makes it a lot easier to write that regex that cleans all those comments out of the entire code base. You would have never done anything like that. I have never done anything like that

[00:24:43] Allan Stewart: as far as anyone can prove. So as we've been talking, we've been touching on a related topic of communicating with other people, right? So we've been focused on like, how does that look in code? But the importance is communicating with other people. Maybe it's our future self, but more often it's people within your team, within your business. If we are talking past each other, if we're not connecting, it really is a matter of how we're going to communicate. base code base code base code base code base code base code base code base code base code code base code base code base code base code base code code base code base code base code base code base code code base code base code base code base code

[00:25:44] Matt Baker: communicating shows up in writing software. One of the ones that's sticking out to me right now is engineer to engineer. I know when I've been in mobs and pairs, if you have people that are very ideologically opposed, you can kind of reach stalemate sometimes about, no, we have to use Angular, we have to use React, or we have to use X pattern, and we have to use Y pattern. And one of the things that's sticking out to me right now is the ability to navigate those conversations. If you can't, you can end up with a code base that's a bit schizophrenic, where you see both people trying to shoehorn in their pattern. God forbid they're coding independently and just racing one another. Even if they're coding together, I think you can see

[00:26:25] Dave Adsit: maybe disagreements that engineers are having. Yeah. Yeah. I think that this is actually one of the hardest things is because we have this habit in our industry of talking about engineering Engineering is very much part of the business. Without engineering, a lot of our businesses would not exist. Well, but I'm going to say the reverse too. Without the people doing marketing and sales and accounting and HR, most of what we build as engineers would be pointless. Good point. In a business context. So we are all in the business, but one of the things that I've seen a lot is just there's some kind of impedance mismatch between the people writing code and the people not writing code. We talk about the world in a different way. We use the same words with different definitions. Just communication is very challenging across that divide in particular. So much so that we've created single single single single in a lot of cases. One of the guys that I used to work with was into meditation and mindfulness and thinking about what he could do at any moment to fix a problem. And he told me once that the problem with communicating with another person is that it has to go through four phases. There's what you think, and then there's the outbound filter that your thoughts get translated through into language. And then the person who hears you parses that language through their own set of filters, and that creates a thought in their head. And very often, maybe every time, what you had in your head and what they have in their head don't match. And so that is where we have, that's where communication has to be robust enough that we are aligned around what we're doing, aligned around what we're doing, even if what's in my head and what's in your head don't actually

[00:29:06] Matt Baker: perfectly match. I think there's some tricks, some tips and tricks you can use to navigate some of that. One comes to mind from Linda Rising. I don't know if she came up with this or she just passed it along in a talk, but she spoke about when you have two people in the situation, like what you just described, Dave, one tactic you can use to ensure successful communication is to have, you know, person A say back to person B what they hear person B saying until person B is satisfied that they understand, and then you can flip and do the reverse. Not too similar from like, or not too different from like the way maybe our TCP protocols work, you know? Did you hear me? Tell me what you heard. Okay, yes, that's right. You know, and then just sit and do that constant

[00:29:51] Dave Adsit: exchange. Yeah, that active listening and replay. And it's more time consuming. Communicating effectively is more time consuming. And just firing off a sentence and walking out of the room and assuming that the people who were you left behind will definitely understand what you did and what you said and what you meant and build the thing that you intended as opposed to ignoring you and going back to what they were doing anyway. So I think a lot of this comes back to the idea from domain-driven design of the ubiquitous language, which is to take the language that you speak and put it in the code. And take the language that the engineering team speaks and align it with the language that the people who are not in the engineering team speak. So do you mean that literally, Dave? Like if my

[00:30:43] Matt Baker: engineer said, or excuse me, if someone in sales said, I just sold the blue component, I can't think of a better name, you would expect the code to say blue component. And that example, you would expect to be pervasive in the code? Yes, I would expect. So language,

[00:31:01] Dave Adsit: is something that evolves. And it's not something that is, with a couple of notable exceptions, it's not something created by a person and then distributed. Language evolves as it is used. And so as I'm talking to the salesperson about the blue component, I would expect us to come to an understanding that makes sense from a technical perspective and from a sales perspective, and ideally also from a marketing and accounting perspective. As well. But at the very least, at the very least, I want my product manager and my engineers talking the same language. I would like to see that beyond the team, but that's not always possible or reasonable. Sometimes you're so disconnected from different parts of your organization that you, A, it's irrelevant, and B, you don't have any opportunity to coalesce around a language. Right. I think I want to say that there's a warning there that if you are trying to create a unified domain model for the whole company, you are doing ubiquitous language wrong. Yeah. Because ubiquitous language is bounded by a context.

[00:32:16] Matt Baker: Can we talk about why? Can we take a minute and talk about why that's true?

[00:32:20] Allan Stewart: Yeah. Oh, definitely. I was just getting to this too, right? Because this is where the other really useful thing out of domain driven design, the bounded context really, comes in at times.

[00:32:31] Dave Adsit: First of all, no one has ever successfully shipped an enterprise data model. And if they said they did, it's because they didn't know how much code existed that ignored the enterprise architects in their ivory tower.

[00:32:44] Matt Baker: Dave, will you state your phone number so people that want to prove you wrong can text you?

[00:32:49] Dave Adsit: You know what? They could, but I won't believe them because I've worked at all of those places that said they had it. And I was in the code and I knew it was a lie. I will only state my phone number, if they state their phone number, so that the people who actually work on those systems can call and tell me that I was right.

[00:33:08] Allan Stewart: I think they just look it up in the person record, because every person will have a phone number at all times in the unified model. Well, a collection of phone numbers with types.

[00:33:21] Dave Adsit: Oh, for sure. Right? So, I mean, and a lot of that talks to, what is clean code? It's code that does what you expect, and it doesn't have a bunch of extra nonsense. And a lot of it, it's, it's, it's

[00:33:46] Matt Baker: code single-digital code single-digital code single-digital code single-digital code single-digital code single-digital code single-digital code single-digital code single-digital code single-digital to approach solving it is a bounded context or you create a series of boundaries in the system and that does something so i'm wondering if we can like talk about what what's actually happening because i don't disagree that introducing bounded context is is the correct solution to uh you know avoid the enterprise data model but uh you know i want to talk about why i think it comes down to

[00:34:24] Allan Stewart: the context part of it because language exists within a context at least in english there are so many overloads for pretty much everything you say you can't hardly speak a sentence without offending somebody because there's an overload of one of the words that you use that was you know very you know triggering for somebody and yet somehow we have to to move on and there are definitions i have a good friend that i would talk with at length on many occasions where he would write like a blog post or something and ask me to review it and i would review it and i'd say okay this is what you wrote but i think this is what you meant he's like oh yeah well if you look up the definition for that word definition three or four or seven is the one that he was thinking of and i was like yeah but i'm not sure everybody's going to be thinking about it that way yeah so you got to have that context yeah just i mean and that's just kind of for spoken language in general having that context and if you're solving a specific problem if you're in code where the code is very exacting it's very technical you need to be able to express things in that context which might mean that for you something as simple as a user you know it might have many different manifestations or your product blue that's going to mean something different to different parts you know shipping they care about well product blue means that it's going to weigh 16 pounds and we have to pay this much in shipping meanwhile somebody else doesn't care at all about that because they care about like how much markup is there and how much you know percentage margins we can get on on blue product yeah i i'm thinking

[00:36:13] Matt Baker: about a an example and i'm going to try this out and it makes sense in my head let's but i think what dave said about all the filters being true so let's let's see how it goes you know i'm going to if you have a store that sells baseball bats um and you write software for that you're going to have something in there called a bat probably uh and and it's a baseball bat it makes sense if you also try to open maybe a sister company using the same software that sold i don't know creatures that fly in the night uh you're going to have bat in there as well and it's sure not going to be a wood thing that hits balls anymore and so you're going to have to clarify because you chose to combine two disparate domains with one piece of software and you're going to have to use a different piece of software you now have an overload of bat and and it's really just a side effect of combining two domains that probably didn't have any any business going together anyway so coming back to the end the enterprise data model i wonder if one of the reasons it suffers is you're just unnecessarily polluting domains you're just saying you can all go together and not not maybe paying homage to the fact that introducing one domain into another affects them both and one of the things it can do is overly overload terms and introduce complexity that you to do that and i'm going to do that and i'm going to do that and i'm going to do that and i'm going

[00:37:54] Dave Adsit: So obviously the solution there is to create a unit of inventory because as a salesperson, the number one thing that you want to do is go out to customers and offer them units of inventory. How many units of inventory can I sign you up for today? Sounds an awful lot like the sales pitch I get from seven-year-olds during candy bar season for the PTA fundraisers. It's not how we communicate effectively. It's not how we, I guess one of the things that I'm thinking about is that a lot of what makes us human and makes us work well is the fact that we bring an emotional or creative element into the logical side, right? So we bring that creativity, we bring that emotion into the code. And so there's more than just the bits when it comes to communicating with people. Right? Right. Right. To evoke an image in your mind, when you read the code, when you read the specification, when you look at the user experience design that was presented by the UX designer, I especially want to do that if I'm a client success manager and something is going wrong for a customer and I need help from the engineering team. I would like you to come along with me on an emotional journey. And if we're not communicating effectively, then we're not going to be able to solve those business problems well on an ongoing basis. I think a lot of that comes back to the idea of terminology. There's a lot of specific terminology that we use in different fields. We have a bunch of things in engineering that we use. Like earlier, Matt was talking about a bit mask. And it would not surprise me if a large number of the engineers, who hear you say that, don't know what you're talking about. But it would surprise me greatly if anybody outside of engineering knew what a bit mask is.

[00:40:02] Allan Stewart: Agreed. Terminology can also be, the flip side of the coin is that it can be a huge enabler. Right? We talk about the problems that happen when you're not communicating. Right? If you're saying the same words, but they're meaning different things, or everybody has a different... name for the same thing, then it's really hard to know what anybody's talking about and to communicate clearly and solve that business problem. But that flip side is that when you do know the terminology, you can go a lot faster. So I'm thinking about some of the times when I've done pair programming with you, Dave. We can talk, because we have worked together for a really long time, we can talk in a lot of shorthand and just say, oh, I want to do something kind of like the... And we use a couple terms. And we know, or at least apparently we know what each other is saying, because we seem to be pretty happy with the result that comes out. You can move really quickly with that.

[00:41:02] Matt Baker: Yeah.

[00:41:03] Allan Stewart: I really like pair and mob programming for this, because down at the code level, that gets you thinking about how do I talk about this thing? For a long time as a coder, I just wrote code solo. And I learned a bunch of patterns and I learned some things, but I didn't know how to talk about them. In my brain. I knew. What the syntax was and how to express it in code, but I couldn't tell somebody, you know, what, what's the difference between a parameter and a field? What do you mean by injection? There's these terms that we can use. And once people are on the same page, once that, once we've had the opportunity to talk about code and learn how to express ourselves well, then suddenly we can go really fast because it's not, well, do you mean something like this? Or do you mean something like that? Or you say something. And they start typing in the code and you're like, no, no, no, that's not what I meant. In the worst cases you devolve into no, no. What I mean is private class foo. And you're telling them exactly what to type, which is very inefficient.

[00:42:07] Dave Adsit: Yeah. I like that a lot. There's, I can think of a lot of times where you and I have just talked about a handful of patterns that we intend to tie together and it represents a whole day's worth of coding to test drive it out properly. And ensure that it covers all of the things that we wanted. But the design session was, I think we should tie this pattern to that pattern to that pattern. And you would say no, but this pattern instead of that one, I'm like, oh yeah, that makes sense. Right. But that only comes because of time spent learning the specialized language of software development. Time spent working together to understand and building. Bringing our own knowledge of patterns and practices. And then applying it by saying, I know this software pattern. I want to use this this way. And you say, well, I've heard that software pattern is like this. And, and then we come to a mutual understanding of the pattern and then we can use the pattern to talk about it. A thing together.

[00:43:06] Allan Stewart: Absolutely. And that applies not just for writing code, but the same things I feel like apply at the business level where we are talking with other departments, where we are figuring out what is it that we should build? What is our company strategy? When you're on the same page with the ubiquitous. Language you're talking about the same things in the same way. And you're understanding when you mean the bat that is a living mammal versus the wooden stick, then you go really fast.

[00:43:33] Matt Baker: I think that if you pair a mob with someone or a set of someone's enough, you can get to the point where you can say things like do the thing and they'll know what you mean. Like they'll, they'll be able to anticipate where you're going and they know, and, and you can really cruise like, like you're, you're both talking about at that point. Then it's. Uh, just a matter of how fast you're going. And you get the keys out of the keyboard. Those are very, uh, cool moments in programming when you get to that point with someone.

[00:43:59] Dave Adsit: And in case anybody thinks that do the thing is an exaggeration. No, you can literally say do the thing. Yeah. No, like we did in that one the other day. And then they, oh yeah. And then they write the code exactly what you intended for them to write. And it looks like magic to anybody outside of. Group. Yeah. So, um, someone did tell me to hurry and make fewer typos today while, while coding in front of a group. And I wasn't sure how I could do both at the same time. Or even either alone.

[00:44:36] Allan Stewart: Well, to be fair, you were the one setting a two minute timer every time that you, well, there were, there were constraints, there were constraints to be, yeah, to be honest,

[00:44:48] Matt Baker: we're going to have to do an episode. About one to be tuned into later. We'll have to do an episode about, um, interesting programming practices like two minute or five minute increments. There's some fun things there.

[00:44:59] Dave Adsit: Yeah. And why every programmer should know the rules to Conway's game of life. Also as an example of poor communication, if you introduce an activity to a mixed group of engineers and not engineers, and you refer to game of life. The engineers. May in fact picture Conway's game of life and the not engineers may in fact picture a board game in a white box with a little cars and people that drive. And you will have several minutes of confusion. Trying to understand what the other person is talking about when they say we should definitely go to college and you, and the engineers say we already went. Yeah.

[00:46:17] Allan Stewart: Did the person interpret that as, okay, we're going to do it? If you give an estimation, is that a promise? Oh, well, you said it would only take about two days worth of work. And two days later, they come back and like, hey, why have you missed the deadline?

[00:46:32] Dave Adsit: My favorite version of that is this would take probably two days. And two days later, they come back and ask how it's going. And you have to explain that it will take approximately two days in six months when it comes to the front of a queue that is a mile long. I agree.

[00:46:55] Matt Baker: And I don't blame them. I think that if I went into a mechanic and they looked at my car and said, yeah, about three days, and I didn't hear from them for two weeks, or I called them after three days and they're like, what are you kidding me? This is going to take a month. I would feel a little bit. But like, I missed something, you know, on this point, for me, I've gotten to the now when people when I have these conversations, yes, no estimation conversations with people at the end of them, I try and recap by saying, I want to say back to you exactly what I think I've agreed to. Is this is this what you understand, you know, and then I get a yes or no from them. Because if you don't, you just there's all these unmet expectations that are going back to Allan's comment. Earlier, there are side effects, maybe of the conversation.

[00:47:42] Dave Adsit: Well, and I think we should probably put a pin in this as well. But when it comes to estimation, there are so many problems with it. And rather than asking someone how long something's going to take, I've gotten to the point now, and maybe this is just executive speak, but I've gotten to the point now where I say it is worth this many days of your effort for you to do something on this problem. That's smart. I think that's very smart. And then and then at the end of that many days, I can decide if it's worth having them continue or not. Yes, agreed. But I think we should probably push that off. Because while that does have to do with effective communication, in some perspective, it's much more tied up into process and culture and ways of working. And I think the key thing to think about today when it comes to estimation, is that estimation is where we reveal that every engineer is truly a grand optimist. Because every engineer, when asked for an estimate, will give you their best case scenario. Maybe they're better than best case scenario. Even knowing after observing the world for however many years they are alive, that their best case scenario very rarely ever happens.

[00:49:07] Matt Baker: Yeah, on that point. One of my pet peeves is when someone says, yeah, you know, I typically just double or sometimes triple the estimates my engineers give me. And I don't know that I fully understand why that bothers me so much. But something you said, Dave, brought it to my mind. And it's just the most annoying thing to me. I just, if someone's doing that to me, I'm going to be bothered by it.

[00:49:30] Dave Adsit: I can tell you why that bothers you so much. Because that is a great violation of flow efficiency. Which we can get into in more detail later.

[00:49:41] Allan Stewart: I think it's also a question of trust, right? We want to be seen as professionals. And so we want people to take us at our word and not be sandbagging. But the reverse is also a problem because so many times we can estimate something and, or say yes, that this is possible or no, it's not possible, or this should be easy or whatever the things are that we say. And then reality creeps in. It's harder than we expected. There's more complexity. The code is more entangled than we had assumed. And suddenly we can't meet that promise. And so being really clear about those things is very important.

[00:50:23] Dave Adsit: Well, so there's two last things I'd like to say around that topic specifically. One is that often yes, no, or an estimate are a poor way of communicating. Go away and leave me alone before you break my mental. And I have to start over for the day because that's an expensive thing for an engineer to do, right? You've built up a mental model. Someone wants to ask you a question and your answer is go away. And they keep asking you something and you finally say two weeks and then they leave. And so you go. I think that that's one of the things that is specifically related to communication. That is one of the things that we get caught up in when it comes to estimation. And I think that the other thing, in that space is that we don't communicate the full context of an estimate. We don't communicate the best case, worst case and median case for the estimate. And we don't give appropriate feedback when we have adjusted our internal estimate. Like I get into the code and I know almost immediately, oh, my estimate was wrong. I should go tell that person or I should just dig in and try to keep the original timeline. And that's where it comes back to communication for me, is that we need to communicate when context change, when information comes in, when we know more than we did. And that can be hard for a lot of people to revise an estimate.

[00:51:51] Allan Stewart: So in my line of work, kind of the specialization that I've taken on software, I really have enjoyed architecture. And for me, one of the things that comes out of architecture is this idea of this, this synthesis between here are the things we can do technically, and here are the things that the business needs. Because if we're not, if we're not building code that is solving a business problem, then we're going to have trouble. We're going to get to the point where we're just not, we're not making money or we're spending too much money on the wrong things. And so communication becomes a really important issue in there. How do you bridge the gap? How do you let people understand, Hey, here, here is a broad vision of, of what we want to accomplish and why?

[00:52:43] Dave Adsit: Well, in the absence of any better idea, I get a whiteboard and some markers and start drawing and talking. And sometimes the drawing is relative is related. Sometimes it's not.

[00:52:58] Matt Baker: Yeah. I think a whiteboard is so underappreciated here. You know, I tend to shy away from big architecture drawings and facts, this point, I feel like I tend to shy away from architecture drawings altogether because they become lies so fast. You know, it's almost like this is a point in time thing that point. So, so I like the whiteboard. Another thing I like about the whiteboard is people are right there with you and they can probe your thought process as it's evolving where, you know, I can't do that if I just give you some PDF. So I know I've always personally appreciated whiteboard sessions when, when I'm trying to learn a topic from someone or when I'm trying to teach a topic topic to someone or, you know, Allan, back to your point, trying to explain the architecture of a sufficiently complex system.

[00:53:48] Allan Stewart: Yeah. There's something about visualizing that is really helpful. And there's, there probably are some times where having something a little bit more formal is useful, but more and more, I find myself wanting to just go with a few different shapes, a few boxes and lines that kind of sketch out the idea of what I'm, what I'm talking about. Even if I'm putting it to a document, that's going to get shared around because some of the more formal things, if I'm going to use UML or architecture diagramming tools, that that half-life of their relevancy is so short. It feels like that it's a full-time job just to keep it up to date.

[00:54:25] Dave Adsit: One of the things I like about having an architectural vision is that it tells us where we're trying to go. It's not necessarily like a representation, of how, where we are now, but it, it helps us see where we're trying to be and then gives people the freedom or it pushes down those decision-making rules so that people can actually make the decisions that get us closer to that as they work in the code. I think important things for me to see in an architectural vision are where are the boundaries and the interfaces. And then I give people the admonition, do the best, you can inside your boundary. I don't want to tell you how to build your piece, unless you ask, I want you to do the best that you can with what you know, with your specialized knowledge, being very close to the problem and solution. And so I think that that's one of the important things about the vision. It's hard to communicate. It's even harder to set a vision.

[00:55:32] Allan Stewart: Going along with that. I think that there's a lot of room for communicating through exercises. Or demonstrations, especially the hands-on type of things where, I mean, we know we're learning as, as people, educational models are improving and whatnot, that people are going to learn a lot better if they do something hands-on, if they can try it out, if they can give it a go themselves, rather than having the professor at the lecture hall telling them about, well, if you were to do this, this is what would happen, but that just doesn't stick. And so if you can find, find exercises that you do, there's one that sticks in my mind, an exercise that I did one time where we were learning how to use a message broker. We were using RabbitMQ and there was this exercise that was set up. There are many ways that you can do message brokering, and this is the pattern that our company has chosen. Here is an exercise for ordering pizzas or something like that. And just watching messages go through the flow of different parts of the system. That was super helpful for me. And, you know, we learned about how to crash a RabbitMQ,

[00:56:39] Dave Adsit: I think that one of the, one of the great things about those exercises for communicating an idea is that you get the really fast feedback. And usually you've got exercises that are guided. And so you have a tutor who is watching and helping to correct and point you in the right direction when you are either making obvious mistakes or getting stuck or whatever, in a way that we don't necessarily have, in our regular daily work.

[00:57:09] Matt Baker: I'm thinking about, you know, exercises to learn and pair coding jumps back out to me again. One of the things I love about pair programming is you can, while carrying out the duties of your job, you can have some fun with it. And one of the ways you can have fun with it is create a constraint where there's one person at the keyboard and they aren't allowed to think essentially they're there. They just need to follow the direction of the other person in the pair. So that person forces the other person in the pair to articulate their ideas well enough that they, you know, the smart keyboard can type for them. And when I think about exercises to learn, you know, effective communication, it's, I think that's a great one with lots of tight little feedback loops.

[00:57:53] Allan Stewart: I believe that Llewellyn Falco calls that strong style pairing and his little quip to go along with that, that I really like. For an idea to go from your head into the computer, it must go through someone else's hands. And that really speaks to communication because it's so easy to run away with the keyboard, especially when you're first learning how to pair program. It's just like, oh, I've got an idea. Give me the keyboard because I'm not going to actually express the idea. I'm just going to turn it straight into code. And I might not even write the code that well that expresses my idea because it's the first time that I'm going at it. If I have to say it out loud well enough that somebody else can type in, what I was intending, then, then you know that you've achieved that level of clarity that yes, they understood what I was saying because they were able to type it.

[00:58:43] Dave Adsit: I really like that tonight we've talked about incidentally two of my favorite techniques for improving your technology org. I've long said that the best way to improve your code is by testing it. And the best way to improve your team is by having them pair. And then later I amended or mob.

[00:59:03] Allan Stewart: I think the final thing that, that becomes really important when we talk about communicating architectural vision, especially is figuring out how do we communicate the value of something that we're doing? Because in the small, when any individual engineer is working on some piece of code, if they get the idea that they want to do something, you know, because it's cool, we want to apply this pattern. We want to use this new framework. We want to do, you know, whatever other resume driven development concept is, It's usually not actually all that bad because it takes time. There's an inertia required in order for that thing to either gain traction and take hold of a database or a codebase. But in the large that can be much more difficult. You know, a lot of times it's easy for us to say, oh, well we want to architecture and all the people are talking about the micro services. So we better start doing some of that and we're not thinking about. the problem. We're thinking about something else. We're thinking about some cool way or technology. We've got this real technology focus of what we're doing rather than a business focus of solving a

[01:00:18] Dave Adsit: problem. Yeah. Most of your customers don't come to you to buy a microservices. They come to you to buy that blue component from earlier. I would like one 16 pound blue widget, please. Please. Did you know it was created with microservices? I don't care what it was created with. I would like a blue 16 pound widget. You know, microservices, I heard it

[01:00:45] Matt Baker: called recently a modern software practice. As in since the stone age? Yeah. I find it funny. Anyway, I'll just repeat what you said, Dave, if I go on it again. But I just think that when we talk about... Things like microservices, yes, definitely a big like squirrel or a big like shiny toy syndrome in the whole industry. And I think this dovetails for me into a lesson that I believe I have this theory that every engineer learns this lesson. If they're lucky, they learn it on something trivial. If they're out of luck, they learn it at the expense of maybe their job or the company they started or, you know, the demotion at work. When you elevate You're building over why you're building it. You're in trouble, I believe. And a way to avoid that is to constantly express the value you're delivering to the people you're delivering it to. I think like if you can orient yourself and constantly be, you know, saying, well, here's the value we're delivering. Here's the value we're delivering. You tend to draw your focus away from, you know, that cool new programming languages or that cool new architectural pattern or that cool new database. And you get back to focusing on the problem at hand. So I might be a bit opportunistic here in raising this point, but I think that I really do think that every single engineer is going to learn that they need to be thinking about why they're building what they're building and who they're building it for way more than they think about the cool tech or the cool new pattern.

[01:02:19] Dave Adsit: 100% agree with that. I think that that speaks to the idea that you should be communicating with people who are not engineers about the thing that you're building. And you can be excited about a technique that you're using to solve a problem, but the technique should not eclipse the problem. Nobody buys the technique from you. And I could be perceived as kind of ragging on microservices. I think that's a great pattern for a specific problem set. I also think that in many ways, it... possibly with additional or different constraints. So many times we fail to learn our terminology and we reinvent it when we actually need the same type of solution again.

[01:03:13] Matt Baker: Yeah, it's interesting. I want to piggyback on that point as well and say microservices definitely has a place. I also believe it's true that it's grossly over-applied in the last, I don't know, seven to eight years.

[01:03:27] Dave Adsit: Well, in some part, in some ways that comes back to communication, right? Apparently, when the first patterns book was written, almost no one was using a singleton. But singleton was one of the patterns in the first patterns book that people could easily understand. And so they started using it in software so that they could be pattern-driven software developers. And the use of the singleton pattern went up dramatically. So I've read. I think the same is true for any exciting new thing. It's like people try to apply the basic understanding of that thing. Because communicating effectively the full context of when something is applicable and when it's not is challenging. And wading through all of the possibilities is also challenging to our human minds, the way we think about software. Again, it comes back to communication. I can explain the singleton to a brand-new programmer really easily. I can't necessarily explain the nuance of an event-driven microservices architecture backed by a streaming data service with document data stores at the edges. I can't even say that quickly, let alone explain it to a novice quickly. So I think that that, you know, that is one of the fundamental problems. Is that communicating is hard work. We need to apply ourselves to do it well. Both within our industry, across our team, outside of our team, into our business. Right? We need to be working at communication. Not least of which in the code.

[01:05:18] Allan Stewart: Well, I think that will bring an end to our discussion about communication today. Really important. It's an important topic in the world of crafting code, of professionalism. We're going to let this conversation pass into the night and recommend that all of our listeners join a community of professionals by attending a Software Crafters group or meetup near you. A lot of them are going virtual in the era of the coronavirus. The Utah Software Craftsmanship Group at utahsc.org meets on the first Wednesday of each month in Draper. And recently, there have been a lot of virtual attendees. Maybe we will see you there.