Why writing is important

Hello, and welcome to Go Time. Today we’re talking about different types of writing, and whether or not there’s anything that can relate to writing code or our day-to-day jobs. We’re joined by two new regulars. First is Angelica Hill. Angelica, do you wanna say hi?

Hi!

And we’ve got Kris Brandow. Kris, do you wanna say hi?

Hello.

And then we’ve got Johnny Boursiquot, who’s here all the time…

Well…

Sorry, Johnny. It’s been a while.

[laughs] He’s “Yeah, he’s a fixture on the wall by now, so…”

I’m like “I see Johnny all the time. It’s like a weekly thing.”

Right, right. Yeah, good to be here.

It’s good to have you, and I didn’t mean to downplay that. You being here is great. Alright, so why don’t we just start off by – Kris, I believe you’re the one who really loves writing. You’ve told us this… So what interests you about writing?

[03:51] Let’s see… For as long as I can remember, I’ve always been a writer, and always wanted to be a writer. I think the first time that I tried writing a “book” was when I was six. I had like “Oh, I just wanna write this, and write a story”, and then I’d show it to my dad; I was so proud of myself. And I kind of just like kept writing. It’s kind of like a lifeblood for me, I guess. It helps me think.

And I actually turned that into a college degree… I went to school for creative writing, specializing in fiction, screenwriting and playwriting. It’s just kind of always been a staple of my life… So I guess that’s the history of me as a writer.

I don’t think your teachers would have expected you to translate creative writing to writing Go.

Probably not. And that’s also the other funny thing about my back-story, is that I tried to avoid tech, specifically software and computers as much as possible… Because growing up, my dad was a computer scientist, and my mom studied computer science, so all the family gatherings were like “Are you gonna go into computers like your family, like your mom and your dad?”, and I was being like “No. I’m gonna be an author. I’m gonna be a novelist.” And then somehow I just wound up right back here…

Alright… Angelica, I think you were also very excited about this one. So what interests you about writing?

I have entered writing via drama and theater. I was obsessed with Shakespeare, as probably everyone (mostly everyone) who has ever met me knows… So I fell in love with the way that writing could bring people’s stories to life, could put emotions, feelings, experiences that some people might find really difficult to express if they didn’t have that medium to just sit, write, rewrite, think it through and really get to a place where they’re presenting what they want to present to the world, in a way that is true to them and their story.

So I started by just loving acting, and bringing those words to life, and then kind of went backwards and realized I didn’t really wanna do acting, and I preferred writing… So - similar to Kris, I went to university for English literature and drama, dabbled in playwriting, it wasn’t all that good, and now I just write for fun… Both code and poetry.

I feel like people are gonna think they’re on the wrong podcast today… [laughter] Johnny, anything about writing that’s really interesting to you, or really has you appealing to this episode?

Oh, yeah. For me, I discovered early on - not even in my career; earlier on in my (I would say) high school career, that writing was about story-telling. Writing was about – imagine you’re a kid in high school who finds writing to be a way of communicating and doing so more easily than they can with words in real life. That was my discovery - that with the right tools, with continuous study and picking up good vocabulary and learning new words, and trying to pick up a new word and using that in a sentence every day, or something like that… Earlier on I was lucky enough - and I don’t know where that came from. Maybe it was a teacher, and if that’s the case, I’m grateful, wherever they are in the Universe now… It quickly became clear to me that in order to communicate with the world, whether you’re present or not, you have that ability to basically take a thought and convert that into words, and somehow still try to capture what you would have conveyed were you speaking to someone else, or people face-to-face… Trying to do that for me has always been something I was chasing, because - again, the power of storytelling.

Fast-forward through the rest of my career, that still remains true, probably even more so today than before, the ability to convey information and somehow put a part of yourself in that communication, for someone else to consume tomorrow, or ten years from now. There’s something just really romantic about that; I gravitated towards that a little bit.

[08:02] And writing is everywhere in our lives, whether we realize it or not, especially because we are in the industry we are right now. If you’re tuning in now - yes, this is a Go podcast… [laughs] We are talking about the effects of writing; but I think writing, whether it be for communicating with co-workers, or managers, or other people within your broader community, or writing code - which I think we’re gonna get into - there’s an aspect of writing that touches on everything… Whether you’re actually creating things for publication in print, or whether you actually have to write down a story before you can tell it on stage, or whether you have to write a course… Whatever the case may be, writing is a throughline across all of that.

So I guess I’m the outlier here, because I always thought I hated writing… And I don’t think I actually hated writing, I think I just had experiences I didn’t care for, where learning it in school - it always felt very subjective, and it felt like the way I would take things or I would try to express things or whatever didn’t seem to translate directly to what the teacher wanted… So it was always frustrating when I wasn’t doing well in classes, or – not necessarily terribly, but it just never felt like it was for me.

But then over time, I’ve definitely learned that when you get into tech, being able to write and explain things clearly, like Johnny said, is incredibly valuable… Even now, especially with us all being remote… But I’ve been remote since well before the pandemic, and learning how valuable writing can be for communicating things that you aren’t there to answer questions for has sort of opened me up to liking writing more… But I’ll definitely say that in the past I was just like “No, I don’t like writing. It’s not for me.”

I will say that – and I’m sure we’ll get into this; I know Kris has a lot to say on this… You write code - when we’re talking about writing, we’re not just talking about writing literature, writing poems, writing a message to your colleague on Slack… We’re talking about physically the code that you write every day - that’s writing. And it is a form of communication.

We’ve touched on this before with Kris in our previous conversation - you’re writing code predominantly for your other engineers. You go in and they read your work, and they edit it, and they – as Johnny had touched on, you’re writing it and maybe three years down the line someone else needs to come, a human being needs to come to your code, read it, and be able to understand and process it. I don’t know, Kris, whether you want to say more on that…

Yeah, yeah, I think that kind of sums up and describes really well the conjecture I have, that software engineering is a writing discipline. I got a degree in the disciplines of playwriting and screenwriting and fiction, and software engineering and programming sits right next to that. I think people tilt their head a little bit sometimes when I say that “Oh, I have a creative writing degree.” Sometimes people say “Oh, it’s sad that you’re not using your creative writing degree, so the degree in your career.” It’s like, “No, actually the skills that I learned in college, taking my creative writing courses, are invaluable, and have made me such a better software engineer, because I went through those courses, because I learned those things.”

You’re creatively solving problems by writing code.

Yeah, yeah. And the actual language looks different, but screenwriting and playwriting are surprisingly very different things, even though they’re conceptually similar… And I think that’s the same kind of thing, where like – okay, code looks quite different, but it falls in line with the rest of the things that you can express, and the rest of the disciplines that fall within writing.

I mean, really within any language community, especially - I’ll speak for the ones I’m familiar with… Especially within the Ruby community, for example… One of the things Rubyists will tell you is that the expressiveness of the language, when you’re writing and later on when you have to read it - because we all know, we read code a heck of a lot more than we write it… The ability to read, and for what you’re reading at least in the English language, for what you’re reading to make sense as if you’re reading prose. Basically, you are seeking to convey clarity.

[12:11] So the more expressive the language, the more words you can use to express the intent, the more it feels like prose, the more it feels like you have more tools at your disposal to convey intent… Something which is very hard. This is what we do all day, every day, whether it be naming rules, or spacing to guide the eyes… I mean, all these things play a role.

Once you realize there’s a connection between the skill of conveying intent in your code, that is not just knowing some esoteric things about the language - really, you’re trying to convey intent in as simple a way as possible, regardless of the language you’re using. That’s always the intent. Once you realize that connection there, you become a much better programmer, you become a much better technologist. Because really, what we’re doing, all we are as engineers, are sort of that middle tier between what the business wants and the technology. They can’t speak that language directly… And believe me, they try. All you have to do is just look at technology out there to see all these drag and drop tools and interfaces… Even Amazon came out with yet another one back at re:Invent a couple months ago… There’s a pursuit within our industry to obviate, to make the need for folks like us who write code, to make us less important, less relevant… Because we can be a bottleneck.

So if we can somehow reduce that and allow the people with the intent and the know-how exactly what they want from a business standpoint, to actually implementing the actual execution part. If they could do away with us, they absolutely would, make no mistake about it. They absolutely would get rid of us. But we are that translation layer. So now we have to write for the rest of us who are working together to basically – again, to take the intent… And now there’s another layer of that, to say “Hey, now I’m writing for my fellow engineers. Now I need to convey intent to them…” But still, the ultimate goal is to take some desire, by people paying our salaries, and to convert it into technology. So there’s a lot here about understanding, and intent, and communication, at all layers of the stack, if you will. And knowing how to write, whether it be to communicate with the layfolks, who are not engineers who are writing code, or whether it be us talking to each other… It’s all about how well can you relay intent through writing.

And I think an interesting point on that too is how that compares to what some of the other writing disciplines look like, and the respect for the writer within those disciplines. Another interesting thing of difference between screenwriting and playwriting is how much the writer is – I wanna say respected, but how big a role they play… And playwriting - when you put on a stage play, you try and stick to the writer’s intent as much as possible. The playwright is sacred. But in screenwriting and in movies the screenwriter is just like “Oh, that’s someone who happened to produce the story.” But it’s the director that we really care about, that kind of shapes that narrative.

And I think too on your point of necessity of the writers, I think another interesting point of contrast there would be with the publishing industry, and books and novels. Often, a lot of people that write books are not professional writers, and they’re just putting together a story because they have the knowledge to tell that story… And you have editors that come in, and those editors help refine and create a more polished story for the end consumers. And I think there’s some interesting things you can pull from those other disciplines into our own, to make building and writing software a bit more coherent.

[16:06] It’s interesting to me that you mentioned that some people would think you don’t apply writing to code… And then it’s not that hard to realize, or it doesn’t take that many steps to realize that people have caught on to that connection and they even experimented with it… So when you see testing frameworks like Cucumber, where you’re literally writing paragraphs to design a test, people have gone as far as experimenting with it.

Writing code is definitely different than writing a play, in many ways… But it’s also interesting that people have come to the point where they can actually write tests in a very similar way to how you would write a story.

Yeah, and I think that brings up another thing I’ve spent some time thinking about, which is kind of the comparison of software engineering is like writing, versus software engineering is writing. I kind of feel that using prose to write your test is more toward the “Okay, this is a good way to understand things, so we’re just gonna borrow this from (I guess you could probably say) fiction, or novel-writing, or that kind of structure of writing, and trying to apply it to software engineering”, which I think is a good first step. It does make tests easier to consume, but it is awkward, because you’re applying an analogy on top of software engineering, which is kind of like any other type of analogy. There’s some like “Software engineering is like gardening, or construction etc.” And it fits well at first, and then you start to see the places where it doesn’t quite meet…

And I think the next step we need to make is “Okay, they have some nice things in these other disciplines of writing. How can we take that and bring it into software engineering and adjust it to make it so that we can write tests that are easy to read and are pleasant to read, but don’t necessarily come with the baggage that comes from, say, the looseness of trying to write things with prose and paragraphs.

So are there any specifics that you would want to focus on first? I guess the first thing for me at least that comes to mind is when you’re learning how to write persuasive papers, you always have to start with a hypothesis of some sort that you’re trying to prove… So is that something that could apply to maybe tests, or something along those lines? Or I guess what connections are you seeing?

I feel like one of the biggest connections we could probably pull is the kind of process and format that most other writing disciplines go through when they want to produce something. I feel like when we write code, we always want to jump into writing the code. That’s the first thing we want. We’re like “Oh, we wanna start writing”, but whether it’s by writing the tests, or whether it’s by writing a prototype and hacking it together - that’s like the first thing we wanna do. And in most other writing disciplines, that’s not what you do. If you wanna write a book, you don’t sit down and write “Chapter 1”, and start writing your story. And the same thing is true – you don’t write the opening scene for your screenplay when you sit down and write it. You have these other documents, whether that’s an outline, or a treatment in screenwriting, or character bios… You have all of these other documents and all these other forms of information that you kind of play and experiment with a story before you actually lay it down in its final form. And I think that’s something that we kind of desperately need to start doing in software engineering.

So many of the projects I’ve been involved in and some of the companies I’ve worked at have a little bit of a culture of writing scope and design docs, but it’s not very robust. And I think what that ultimately leads to is kind of the result that you’d wind up with if you just sat down one day and started writing a book and tried to write it all the way through, instead of sitting down and kind of planning it out some more.

And I think what’s important to note there too is that it is contained within the software engineering sphere - I think there are other people that do other type of planning and documents, whether it’s product people, or business people… And those need to be done, but I think those are kind of separate from what software engineers need to do to produce those pre-code documents.

I think we do try to do that, we’re just not consistent about it.

Yeah.

[20:04] Over the years I’ve heard all kinds of tooling, and mnemonics, and things that we sort of try to introduce into our workflow as engineers before we jump to the code. And you have folks that are on the extremes of that, you have the folks who are like “Oh, let’s just start writing the code and we’ll figure that out as we go.” Because working code is better than whatever the thing. I mean, they have a point, to a point…

And then you have those on the other side, who get stuck in the analysis; the analysis paralysis. They spend all their time in drawing tools, creating boxes and arrows, and never actually execute anything. I think the ideal, really like in most things in life, is to not be in the extremes of things. it’s to really find the middle ground that allows you to make progress, still while having a plan… And then you make an incremental change. The same thing we preach engineers, basically - that immediate feedback loop, or that short feedback loop… Basically, you make a change, and see what’s broken, and you make an adjustment again, and you make more progress… So that feedback loop - basically, we don’t have to jump right into writing the code. You write the code when you know what you’re building.

Sometimes you don’t know what you’re building yet, right? So I don’t subscribe to “Let’s just jump into the code and then figure it out” thing… Which is why personally one of the tools that I use right off the bat is basically – if I can use either readme-driven development, or jumping into something like LucidChart, or draw.io, whatever it is, just to get an idea of what’s going on. Another tool I use is websequencediagrams.com. I’ve been using that for years to create sequence diagrams; how do things interact, how do components within the system interact with each other… A lot of times I will discover what I’m missing when I go through that exercise.

If you take nothing from what I’m saying right now, sequence diagrams - they are your best friend; trust me on this. Because it’ll force you to think, “Okay, what’s the entry point into this thing that I’m building? Where is it coming from? What is the shape of the data? What do I need here? When I get to this point, what is the other thing that I need?” So it’s almost like you’re weaving a story, you’re making a plot; really, it is storytelling. If you squint, it is storytelling, because it’s like “Who is the cast in this story?” This execution of a business process, or whatever it is. Who are the actors? Who’s involved? What’s the setting? What does the stage look like? What’s the environment? Or “This is best-case scenario: this actor says this, this one replies that…”

So if you see the world as that stage and you can script things, you can then account for “Okay, well if this doesn’t happen, this actor then has to do this.” Also, you’re adding improv into the whole mix. So that allows you to see a much bigger – so again, not taking that to an extreme whereby you’re trying to think of all contingencies, and things like that, but starting out with some high-level view of “This is my desired end goal, and these are the actors that are a part of this ecosystem, that are a part of this play that I’m trying to put together.” And seeing what’s the interaction back and forth between them - that’ll help you uncover a ton of problems upfront.

Again, even if it’s a back-of-napkin drawing of what it is you need to account for, that puts you in a way better position… So some planning upfront does wonders. And again, this is a technique that you can learn from the writing world. You can bring that into your engineering practice, and it works wonders.

I think an important thing on that too is this is a very new thing in software engineering. Software engineering is a very young field as it is, so I think it’s important to explore and find the tools and continue to try and find the tools that work for this process, for this way of creating software. Because I think sometimes we start doing something and then the whole industry kind of converges and it becomes best practice, and that’s what everybody does… It hasn’t had enough time to actually become a best practice. We’ve been doing it for two years; there’s no way that this thing is a best practice. We haven’t written enough software with it.

[24:13] So I think it’s important, whether it’s diagrams, or whether it’s prose writing, or whether it’s actively rapid prototyping… Whatever it is that you use to explore this space and establish what it is you’re gonna create. We need to really try and explore the edges of that before we even begin to think about settling it down. I think a big part of that exploration is also documenting how we’re doing these sorts of explorations.

I think oftentimes we don’t document that process, because it’s hard to stop and be disciplined about writing down what you’re doing when you’re in this frenzy of coming up with good ideas and being all excited about everything… And it seems difficult to distill that down into something that’s generally useful for people… But I think also at this point in time we don’t need it to be generalized. Just write down what you’re doing, write down what you’re thinking, write down the process that you’re using and we’ll generalize it later. But I do think that it’s super-important not to cut off or constrain how we go about this design and planning process for our software too early.

I find that if you also tell yourself what mode you’re in, you’re giving yourself the permission to ideate, if that’s the stage of the design that you’re in. Or if you say “Okay, right now I’m in spike mode. I don’t know what I don’t know. Doing TDD wouldn’t really help me much”, because really, you do TDD when you know what it is that you want to build, what it is that you’re trying to get. That’s when TDD is useful; not when you have zero clue to what you’re building.

So depending on what mode you’re in… Am I in information gathering? Do I need to go and read a few Wikipedia articles to know what a particular topic or theory is? It’s okay to jot down notes, it’s okay to not be organized, it’s okay to just be free-flowing with ideas as they come… Because that’s the mode you’re in.

Once you’ve done enough information gathering - which shouldn’t last too long… How long that is, I don’t know; that’s depending on a case by case basis. But the idea is to have enough to have a certain degree, a certain level of confidence, given the objective, that you kind of have a general idea of what direction you need to go; you have a general idea of what it is that needs to be part of your solution… And then you refine from there. But give yourself permission to explore, give yourself permission to think, as opposed to jumping into the code and then trying to do the thinking as you’re trying to do the execution. It’s not “Ready, fire, aim!” [laughs]

Do you think some of this is made worse by the fact that when we’re first learning to code, whether it’s university or whatever, a vast majority of the things we do are on an individual basis, and then we get thrown into basically a company, a team, whatever, where we have to work with others, and processes that sort of worked on our own start to fall apart because we need to be communicating with other people?

An example I can think of is like an author who’s writing one novel can probably get away with whatever process works for them. But if you have a whole team writing TV shows or something, that’s very unlikely to work. You can’t just have one person keeping everything in their head; the whole team has to communicate on character development, and things like that.

This is actually something that I’ve been thinking about recently… Because I saw a thread on Twitter where someone gave a really good explanation of what – I think it [unintelligible 00:27:30.18] continuous integration, but what extreme programming and pair programming and all the [unintelligible 00:27:36.00] what was the genesis of that, and how it was more about synchronous, team-based software engineering, versus what we’re more used to, which is the asynchronous, individual-based software engineering.

[27:52] And I think a lot of the time when we think about writing disciplines we think of that kind of asynchronous, individual-based – if you talk about novel writing, most novels are in that way. Screenplays, plays - most of those things are written that way. Sometimes you’ll have a couple of people… But as you pointed out, TV shows are absolutely not written that way. TV shows have a writers room, and everybody is in that room and everybody is working together… And those are two extremely different methods of writing, and you can’t really take the techniques of, say, the individual way you write a novel and just pull them over to a writers room. That won’t work. And that’s sort of the situation that we’re in right now as an industry. Everybody was excited and talking about this writers’ room style of doing software engineering, and we just started plucking the tiny little things that we saw were like “Oh, that sounds nice. That looks nice.” Like, “Oh, yeah, we can sort of do pair programming. We can sort of do test-driven development. We can sort of do continuous integration.”

I think continuous integration is a really interesting point here too, because it’s like, we’ve taken the term continuous integration and left what it means. It’s like, continually integrating. That means you’re literally continually putting all of the code together, which implies you don’t have gates where you have to stop and check. It’s like, the code goes in, and you can check it afterward… Which, ironically, is like some of the ways that novels are written - you put it into form and then you send it to the editor. You don’t say “Oh, can I add this paragraph here?” before the editor allows you to put it in. But we’ve taken these terms and then we’ve just tried to put them into a different domain, and I think what would help here is if we recognized that and separated them, so we understand “Okay, these are the techniques you use if you’re gonna do an asynchronous, individual-focused software development process, and these are the tools that you use for a synchronous team-based development process”, and have a good understanding of that, and not try to co-mingle the two.

I assume that some of those could be not co-mingled in the way that you’re referring to, but if you’re building one small part of a project and it’s sort of siloed off as “John’s going to build this one specific piece”, you can kind of in your head at that point use a little bit of that, I guess… But then the hard part is communicating that to your team later, which - I don’t know if that would end up causing more problems than just sticking with the writing room style, where you have a whole team the whole time.

I think the writing room style is definitely a bit more difficult. I mean, it’s extremely difficult now, because - pandemic, you know; we can’t all be in the same room together, we can’t all be working in close quarters with a larger group of people… But I do think that the techniques are adaptable to asynchronous-style programming, but you have to be much more disciplined about them.

I think the continuous integration example, once again, is a really good one, because if you have continuous integration, and you wanna apply it to individual-based development, you have to trust that an individual will not be able to put things into the codebase that will cause catastrophic problems… Which means that your testing infrastructure needs to be really good, everybody needs to understand the style of the codebase, you probably need to do larger periodic reviews of your codebase to make sure that the style hasn’t crept in a way you don’t want it to… And I think the problem is that unlike with the synchronous method, where if you don’t have these things, if you don’t have a good testing framework, it will be extremely painful.

In the asynchronous method we just kind of deal with it. If the tests take a long time to run, we resolve that by running the tests less often. Or if the tests aren’t as solid as we like them to be, we kind of just get away with that by having more code review, or spending more time on code reviews. So I think there’s a lot of good things we can pull from the synchronous style into the asynchronous style… But I think back to your original point, I think there are some times when we really do wanna break up software and build software into pieces, where individuals can just go off and write things on their own… Because at a point – you can’t have a writers’ room with 200 people; that’s too much. So at a point you have to start breaking it up if you want to produce these larger and larger things. And I think we just have to navigate and explore that space in a way we haven’t yet…

[32:03] I think base level involves just a lot more discipline around understanding that the things from the synchronous style are really adaptable and really good to have. I don’t think anyone would say “I don’t wanna have a robust set of tests for my software.” Of course you do. And I think the thing is to actually build in those habits to our processes to make sure that we are doing and adhering to them and we’re not letting that slip just because we can.

And I would say it is very much kind of outside of just the engineers in the team. It needs to be a team-wide process, discussion, conversation. So like I have a product manager, and a big part of setting up this kind of process is the product, the project, the engineer managers, all the engineers getting together and deciding “Okay, this is our release schedule. Okay, this is how we’re gonna chunk out work. If you’re working on a spike, are you also gonna do the proof of concept? How are we gonna allow the rest of the team to have input on that? Are we gonna have a demo? Are we gonna have everyone come together and decide who’s pair-programming what?” I think it’s really on a project by project, but also a team by team basis… Because a lot of the conversations I’m having with my engineers when we’re thinking about huge projects we’re building out are “Okay, is this something that you feel like you can’t just go away and do by yourself? Is the rest of the team okay with you going off, doing a proof of concept and coming back? Or do we wanna have a working session? Or do we all brainstorm all the different proof of concepts we could do, and we all come together and then we go into development?”

So I agree very much with Kris, in that we’re in a place where we really need to be open to just trying stuff out, experimenting, seeing what kind of projects are able to be split up, and what projects really do need to be more organized and much more held close to the whole team being involved. But I would say this is not just on the engineering; everyone in your team needs to be bought into this, because if the engineers are working in one way, and then you have a project/product manager come in and be like “No. What are you doing?!”, then that can throw a wrench in the beautiful processes you’re trying out.

I have a theory…

You have a theory…?

Yeah. And it is based on sort of lived experience. I think in large organizations, where the time from idea as communicated by the product team or the leadership, or whatever, what have you - the time from idea coming down in your team having been designated as owning a piece of that to bring into fruition, the time from idea to actual execution is so long. The bigger you are, the more levels exist between that idea and the people doing the execution in terms of the coding - the more those layers, the more the engineers, as soon as they hear anything about, they get a general idea, a general sense of what needs to be done, they know by the time all the dust settles they’re gonna be waiting for so long…

So I think there’s this sort of impetus that as soon as I get some degree of clarity, I wanna start jumping into the code, because I don’t know when this thing is gonna change, is the carpet gonna be pulled under me while I’m doing this… There’s this desire when you work in very large organizations - you want to contribute, you want to be effective… Which is very different from when you’re in a startup environment or a small organization; you might have a handful of colleagues where the distance between idea to you doing a spike, and experimenting, and doing R&D, doing a prototype, whatever it is - there’s so much less bureaucracy and layers between those two things that this is the point where you do need to spend a bit more time thinking about what needs to be done… Because you can just hear something in the hallway and be at your desk cranking out code the very same day, just to get something working… And perhaps in some environments that is exactly what you need to do if your survival depends on how fast can you ship features today, and whatnot.

[36:11] So I think what we’re seeing here makes sense, but some of it is gonna make more sense, depending on where you are in your career, where you are within the organization in which you work… So it’s not one broad brush saying “Hey, we should all do it this way.” There are lots of lessons here, across the board. Some of it is gonna apply more if you are in a small team, with fewer layers, and some of it is not gonna work out so well if you’re in a much larger team, with a lot more layers between you and those ideas. Again, lots of ideas, you kind of have to – as an engineer, what you need to know, your maturity comes in the ability to discern which environment am I in, and which one of these tools is applicable in this environment. That’s what machines can’t do for you; that insight, that gut feeling or that maturity that comes with doing the work, working with other people, communicating with other people, the writings that you get, the writings that you need to send back up… All these things - these are the things that play a role into your ability to be effective in those environments… Knowing which environment you’re in.

That’s something that time is gonna help you get better at. Unfortunately, there’s no quick way to acquire that knowledge. But over time you should be focusing on basically asking yourself - every time you get a promotion, or every year, or whatever cadence you wanna pick - “How well am I able to discern from business to execution how effective can I be within this environment?”, where effectiveness is not judged by “How quickly can I get to writing code?”, it’s “How quickly can I actually take the intent and do something with it?”

Yeah, I think that brings up an interesting thought in my head, of how we as an industry compare ourselves to construction a lot, which I think is not a good comparison. We’re not really anything like it… But I think an apt analogy or metaphor here would be - you know, if you’re gonna build a small shed or something, a small building, you can more or less hop into it; you don’t have to do a lot of planning. But if you’re gonna go build a skyscraper, you need to do a lot more planning, and there’s a lot more people involved, a lot more logistics.

So the way that you build those two different kinds of buildings looks extremely different. And I feel like we as an industry kind of don’t like that, and we just wanna have “Here’s the one way that you build software that’s applicable to building a shed and building a skyscraper.” It’s like, no, those are two very different types of things, and the tools you use for one are obviously very different from the tools you use for the other, and what would be appropriate for one is not appropriate for the other.

So I think to your point, Johnny, we have to do a lot more – I think not just people learning this as they go, but us as industry taking more of a conscious effort to sit down and say “Alright, figure out the scale of the type of software that you’re trying to build, and then we can tell you and help you with what tools that you should be using.”

So we’ve talked a lot about the prepping phase… Sort of getting up to how we can be better at planning for when we’re building something. Are there parts of writing that you think apply to the actual process of writing code, and like once you’re actually into the writing phase?

Absolutely! I think this is kind of like a combined – as you’re writing, and then as you’re maintaining the code that you’ve written, a really good thing that we could borrow from other disciplines is this idea of like a manual of style, where it’s more about guiding people so that we all stay in the same area, instead of giving people specific rules. That was like a really messy explanation.

So this is what I’m trying to say - I think one of the things that we can borrow from writing into software engineering is this idea of kind of doing continual comprehensive reviews of our code as we’re going, to make sure that it’s all in sync and it all makes sense.

I gave a talk at GopherCon a couple of years ago that hit on this point a little bit, where we were really good at the copy-editing level of reviewing code, where you can find your syntactical problems, or your misuse of APIs, or some bugs that you’ve written… But they’re very localized, usually, to like “Okay, this specific thing that I’m reviewing for your code.” And it’s really hard, especially with our tooling, to go review “Oh, I know that we have this thing, but it’s similar in this other part of the codebase, so if we’re gonna change it here, we have to change it over here as well.” And as codebases get larger, that becomes harder and harder to do… And I think that’s the role that styleguides play, or manuals of style play - it’s in helping you catch those sorts of shifts and changes in your codebase as you go. And I think the size of your manual of style shifts as your codebase or as the collection of codebases you have grows.

When you start, you have a very small manual of style, because you don’t have much code. And then as you get more and more and more code, you add more and more to it, and the purview of what you’re adding shifts as well.

For instance, the Chicago Manual of Style is like 1,000 pages, but it started out as literally just a bunch of stylesheets for the University of Chicago Press, for the books that they were writing. And they were like “Hey, these are pretty similar, so let’s take them and compile them together, and then have some general rules of writing.” And basically, every publisher has a manual of style, which is like when you go pick up a book from O’Reilly, or from No Starch Press the books all look the same; they have the same feel, they’re written in the same sort of way, even though the authors are always different. And that comes out of the manual of style and the editorial process. And I think that’s something that we should definitely borrow into software engineering, so that when you see a codebase that you’re working on, you’re like “Oh, this group of people wrote this codebase.” You shouldn’t be able to say “Well, Angelica wrote this part of the codebase, and Jon wrote this other part of the codebase, and I can definitely tell, because things are so different in their styles.” You shouldn’t be able to hear individual people’s voices when you’re reading that code.

[44:26] If I may, I think in the Go community, or the Go programming language more specifically, I think it is harder to see individual styles come through… I think that was a desired effect of the originators of the language, that it all flowed similarly… Which is one of the things that I, when I’m advocating for the use of Go, I’m like “Hey, you can go and take a look at any Go project on GitHub, and it’ll be readable to you.” You may not know exactly what’s going on in terms of the domain, what problem it’s trying to solve, but you will be able to read that Go code. That’s not true for every language.

I’ve seen – again, because I’m familiar with Ruby, and most recently, prior to Go, I could definitely tell which co-worker wrote what part of the codebase, and their imprint on there. And there’s nothing wrong with that per se… Where we run into trouble is if we try to associate ourselves too much with our tools.

To use the analogy you used, about the publishers and their style guides, if somebody hears that “Okay, you’re gonna be contributing to this book, you’re gonna be writing this book or be a contributing author, or whatever it is, but your voice is really not gonna come through that much, because we follow this style guide”, you’re probably gonna feel a little less enthused about writing. Because we want that to be an experience. You want somebody to experience you through the pages.

And again, because when I read those books, I do feel that the style is consistent, that may be the nature of technical manuals, and technical things. That’s certainly not true for novels, or sci-fi stories, or what have you. You are definitely gonna get a feel for “Okay, this particular author - I like the way they write.” That’s something you want.

But if we remove ourselves from what we are hired to do, if we decouple ourselves from our tooling - like, I’m there to solve a problem, not to necessarily write code. So my individuality, my traits as a person - I don’t really care. I wanna enjoy writing the code, but I don’t really care that somebody can look at a piece of code and say “Yes, that’s Johnny’s code.” That doesn’t matter to me as much, right? Or it shouldn’t, I should say. And again, I’m speaking for myself here.

So I think in the Go language there’s less opportunity for your own – obviously, you can understand the difference between code written by somebody who’s a veteran, versus somebody who’s a junior. I think that’s true of every language. But beyond that, given similar experience engineers, the fact that I can’t quite tell without doing a git blame, the fact that I can’t quite tell who wrote that code - I think it’s a feature, not a bug.

So I think you should find ways to express yourself and demonstrate your individuality through perhaps your writing, how you communicate with other folks on your team. I think there’s way more opportunity for that, whether it be written, or verbal, Slack, short messages, whatever… I think these are the places where you have a greater opportunity to communicate and do so quite well, as opposed to trying to do so in your code.

[48:02] So I think I probably explained what I was saying wrong… I think voice was probably the wrong word to use there. I guess the thing that I’m kind of aiming at is less so – I think for most experienced Go engineers, we do write Go in this very similar way, even if we’re expressing very different things, and I think there’s some space for self-expression within those bounds… But I think we’re all kind of familiar with the “Oh, this Go was written by a Java programmer” or “This code was written by a C++ programmer”, that sort of thing. It’s less about the expressiveness and the voice of the individual person and more like trying to borrow idioms where they don’t really fit into the language.

We have a language, we have our own idioms, which result in a specific type of style that you can see. When you sit down and you read Go code that was written by an experienced Go engineer, it does have that certain feel that you’re talking about, Johnny. But if you kind of just pick up Go code that might be written by someone who isn’t as experienced, then it doesn’t have that same feel. And I think what style guides and manuals of style can help us do is really help people that don’t have that experience and don’t understand the idioms as well understand them, so that they can more quickly write Go code that has that feel and that style of the Go code that we all love.

To put this into a concrete example, the thing that keeps sticking out in my head is you often hear people talking about keeping the happy path on the left, and everything else sort of gets indented as you go through code… But there’s nothing that forces you to do that with Go. I think that’s just something that all of us as we get more experienced realize that having that style consistent is really useful, so we all just sort of do it.

So I assume, Kris, that’s what you mean when you’re talking about style guides; it’s things like that that aren’t explicitly necessary, but can be really helpful when you’re jumping through the code, to sort of always know that it’s gonna be in that same style.

Yeah, I think that’s exactly a good example of something that would go in a manual of style. And I think we have that. In code review comments, that’s one of the things - you outdent the success path. But I think sometimes we just need a little bit more nuance to add to there, to help people understand why.

I’ve gone through this process with a lot of my co-workers, where I’m like “Oh, we don’t need to use an if-else here. We should rearrange the code so the success path is not indented.” And when I explained it to them, they were like “Oh, okay, I understand that. I get that now.” And I think that’s kind of what the purpose of what a lot of manuals of style tend to be - as you get more familiar with the manual, you have to refer to it less, and it just becomes something that you understand… And sometimes you understand how you should break the rules of the manual and where it’s appropriate to break them and where it’s not appropriate to break them, which I think is a general thing that comes with rules - you’re not really allowed to break the rules until you understand them. I think that could be helpful, but I think that’s the missing gap right now when it comes to really having codebases that a wealth of people can kind of contribute to. Because I think it’s still pretty hard to hire experienced Go engineers.

We’re a very popular language, and I think it takes a number of years of writing Go full-time, and especially writing Go around other experienced Go engineers full-time before you can really write with that style… Because I also have known people that have written Go code for a long time, but they’ve written it surrounded by a bunch of people that were writing Java Go, so their style just becomes Java Go, and they’re not incorporating and feeling that same level of the Go style.

Is our idioms, or the idioms that we value so much – when we talk about idiomatic Go, for the longest time, and I think still to this day, there’s a strong… If you’re a newbie to the Go community, it won’t be long before you hear about “Oh, this is not idiomatic Go that you’re writing right now.” Or “How have you done that? You’re writing Gava, or Guby” or whatever. So there’s this hill that you have to climb. In addition to learning a language, as a newbie you now also have to learn the way that the people that are in this community want you to write in the language. So there’s like two barriers there that you have to surmount.

[52:11] In his article, Dave Cheney, who wrote The Zen of Go - we actually had Dave on the show to talk about the Zen of Go. I think this was a talk at GopherCon or another conference, but he also - as he usually tends to do - wrote it out as well as an essay. And he talks about that very problem, that basically we create this artificial barrier that perhaps those of us who have been doing Go for a long time don’t realize is a barrier… That we put in front of people that are learning the language, and thereby it might actually end up having a negative effect in the adoption of the language by those people. Because if they see us as being a bunch of snobby, elitist people who want the language to be used in a certain way and to be written in a particular way, whether it compiles or not, basically eschewing the technicalities of it, then that can be a turn-off for some.

And it won’t be long, if you go search through the Reddits and things like that, to get that sense that some folks didn’t really like, regardless of the language itself, that very specific aspect of the Go community… Because we just sounded kind of elitist in our way of saying that “Hey, you should be writing Go this way.”

Now, as somebody who’s been doing Go for a while, the value of idiomatic Go for me is, again, that I can go in another codebase that has been written by long-time Go developers who have been writing Go in the idiomatic way, and that helps me, reading that code, understand what’s going on heck of a lot faster than I would otherwise. So that’s the value.

Again, detaching the tool and the end goal, we should all write idiomatic Go code. Idioms are a thing that communities develop naturally, for communication purposes. It makes communication a bit frictionless, because everybody knows – you know, when my teenagers uses some slang terms I have to go look up sometimes. I’ll try to keep up with the times, you know? So when they’re talking, in order for me to keep up with what they’re saying, I have to also go out there and learn; I have to keep learning.

So my point here is that idioms are a tool for us to communicate better. That same tool can have a negative side to it if we use it as a barrier for those that are basically trying to adopt the language. What we can do as those who are already in the community, that find value in the idioms, is to outstretch a hand and say “Hey, I know you’re getting flak for not writing in an idiomatic way, but here’s what would make it more idiomatic. Yes, I know you wanna ignore your errors here, but we don’t like to do that within the Go community. We want you to handle your errors. I know it might be a little verbose, but this is the reason why.

Again, these are opportunities to help somebody out who is coming from a different language; or perhaps Go is their first language, and they have really no idea and they’re just going with the flow here. It’s an opportunity for us who are already part of the community to make it more welcoming by sort of helping to remove those barriers… Or at least when those “mistakes” are made, when you see that, to not pounce on that individual, but really say “Hey, your solution works. It compiles great. That’s good. You’re learning, and when you’re learning it’s not about making your code perfect, it’s about making it work. Now that you got it to work, this is how you can make it more idiomatic, more like what you’re gonna see out there in the Go community, because of the value that we ascribe to that thing… And here’s the why. Not just because we think we’re cool, but here’s the why.”

So again, the tools and how you use them make a huge difference.

[55:55] I think a style guide that explained exactly why would be hugely valuable. As a newbie I have had multiple people tell me that my Go code is not the way that Go should be written… And that is my first question, I’m like “Why? I need to know why.” I google around, I’m like “Is there a Go best practices style guide I can go to?” And I have wonderful, helpful people who direct me to good Go, that I can read through and look, but there’s no concrete place where I’m like “Okay, this is the good Go style guide as Kris referred to it”, that I can follow and see where I can take liberties and structure it differently, and what I can’t, and what I need to learn and stick to as someone trying to learn the language.

On that as well, I think part of the – maybe it’s like the marketing of Go that we’ve kind of bungled over here… But I think there’s this kind of way that we sell it where it’s like “Oh, the syntax is so simple. It only takes you a couple days to pick it up.” But there’s a lot more that we expect of you when you write Go than just being able to write the syntax. So I think that’s something that we kind of – I think a manual style can really help with that, help people understand, like “Yeah, you can pick up the syntax in like a weekend, but it’s going to take you a very long time to sit down and understand all of the idioms that we have, and why those idioms are there, and how you use them, and why you might wanna violate them sometimes, and really understand the nuance of that.”

I feel like a manual style can shorten that. It’s the same thing with go fmt, where it’s like “Okay, I don’t like how it does it this way.” But we as a community have decided that this is how we want Go code to look and to feel. But there’s other things like go lint, where it’s like “Okay, maybe for this specific situation we don’t want to adhere to this rule”, and there’s ways of ignoring that rule, and specific instances and specific circumstances. I think we just kind of need more of that, and need more of that explanation.

For sure.

I would say another thing is picking the right time to enforce or tell people about those style guide things… As an example, if I was gonna start writing a book with O’Reilly or some other publisher at some point…

Is that a hint?

It’s not, actually…

Oh, okay… [laughs]

I haven’t talked to O’Reilly, so… But I doubt the first thing they’re gonna do is send me their style guide and say “You need to follow this style guide.” Instead, they’re gonna be like “Give us a rough draft and outline. Let’s go through these steps first”, and then at some point we’ll have to get the style guide involved and we’ll understand why it’s there… And they could even explain, “We like the style to be consistent, because then the audience knows they can pick up a book and it’s gonna be in a similar style that they expect, and it really helps the reader.”

I think it’s the same in Go code a lot of the time, it helps people reading the code. That’s the biggest benefit almost always. But knowing that and knowing when to actually present those, versus somebody who’s just learning the language they’ve been programming for two weeks, and they have a bug they’re figuring out, and then somebody jumps in and says “Oh, this isn’t idiomatic.” It’s like, “Is this really the time to be bringing this up right now? Now you’re just making it a barrier for no reason.”

At that point they might just be like “Oh, I’ll just try Python then.” [laughter]

And I think that’s an interesting point too for something we were talking about earlier, which is when and how we do code reviews… Because I think sometimes people do start to focus on “Oh, this isn’t idiomatic” at the code review, because that’s basically the only tool we have in affecting what the style of the codebase is. A lot of places, if you’re like – you know, the dreaded technical debt of trying to get that scheduled; time to go back and clean up the codebase and add consistency is just not something that we’ve built into our processes.

I think that we as a community, and then I think as a wider industry, need to understand we can’t just have one code review. We do have to sit down at periodic points and look at the whole of the codebase and make sure that we have this consistent style… Because that’s just like maintenance. I kind of think of it – I have this analogy of like your kitchen; if you never clean anything in your kitchen until you need it, it’s gonna be a lot harder to clean things, and your kitchen is gonna be absolutely disgusting… And then at some point you’re just gonna clean everything and your kitchen will be beautiful and you’ll be so excited… But then if you don’t keep cleaning things as you use them, you’re just gonna get back to that bad state… And I feel like that is exactly what we do with our software so much; it’s like “Oh man, we’ve done all of this so bad.”

Cleaning your kitchen is like a rewrite. Instead of just cleaning it, we demolish the whole kitchen and build a new one every time…

[01:00:16.23] That’s expensive.

Yeah, it’s extremely expensive… And we just need to have better ways of going in and being like “Okay, you just have to clean the pots and pans and the dishes. You can let them sit for a day or two, that’ll be fine…” But maybe you should let them soak, so it doesn’t get all really difficult to get the dehydrated food off of your pots and pans. It’s okay to leave things for some time, but we are going to come back, and we are going to clean the kitchen, and we have to do that with our codebase. We have to come back and we have to clean up our codebases. We have to just be good citizens and good maintainers.

I guess this has me thinking of when I first started working at Google - they have like two separate different reviews. One is like a code review, and the other is like a style review… And until you get – I think they call it proficient; I don’t know what it is… But there’s some sort of style thing in any language you’re gonna write code in, that eventually you have to go through a separate review that sort of reviews the style for writing that code, whatever language it is…

To give you an example, the first couple of Java things I wrote basically had to be reviewed by one person who’s reviewing the code for correctness within the team, and then there’s another person who is an expert in Java (that’s the best way to put it), so he’s a veteran, he knows what the style guide there is… And he can look at the code just for style stuff.

And eventually, you write a big enough piece of code that you submit that is meant to demonstrate your understanding of the style guide of Java, and from that point on you don’t need the style guide review… I mean, somebody can still point something out in a code review, but it’s not necessary from that point on… And I’m kind of wondering if that approach might actually be better for some companies, where you really help people understand your company’s style guide and the things that are important there, and then you sort of move on.

I know at the time it’s kind of frustrating to be like “I’ve gotta go through both of these reviews”, but you do learn a lot in the process of how this company does it. And I’m even thinking of I worked with one team that did Ruby, and Johnny, you’d mentioned you could tell who wrote what… But there was different ways to iterate over a slice – or not a slice; a list, I guess, in Ruby… [laughter] There’s different ways to do that, and the team actually had me changing to the style that they used. And at the time, it’s kind of like “Oh, that’s annoying to figure this out”, and to adapt to their way… But now that I’ve coded longer, it makes way more sense. I completely understand why they pushed for that. And I guess I’m just wondering if having that separate style guide review that’s sort of baked into your process early on might be beneficial for some teams.

Yeah, I feel like that’s a bit like how when you’re writing a book, you have different types of editors. So you have a story editor, and that person’s there to make sure your story is consistent, and that it’s accurate, and they do some fact-checking… And then you have your copy editor, which is just the person that’s like [unintelligible 01:02:50.20] are you using words correctly, do you have typos… Just really making sure that you’re more or less meeting a section of that manual style.

And I think that yeah, absolutely, we should have more of those types of reviews, because just because you understand the space doesn’t mean you understand the language that well… And I think it can be hard to – I think it’s definitely harder, especially as companies scale, to have everybody know everything. I think that’s kind of impractical. And having a few people that specialize and are experts in something yields a lot of value, as we’ve been saying, in the ability for everyone to read and to understand and contribute to the codebases.

So yeah, I think you can really just take some expert Go engineers and have them just be able to review all of the code reviews that come through, and make sure “Is this Go-style? Is this meeting the idioms that we have?”

[01:03:50.26] I also think it’s easier come review time to only focus on one thing. I know when you get a big chunk of code and it’s like “I’m reviewing this for style and for correctness and these other three things”, at some point it’s hard to cover that all in a review without going through it multiple times.

I’ll start a fight with Kris and say that I don’t think you can afford to review the entire codebase and clean up… Or at least I’m speaking from the point of view of the business here. No business wants to pay developers to make things pretty, and the words that we would use as engineers - more maintainable, easier to ship features and make things faster etc. While there is a case to be made for that, the business is gonna see that as a cost… Because it’s much easier to see the time engineers are spending and putting it into something that is really arbitrary… Unless you’re really good at tracking and you can tell exactly that these improvements you’ve made last month to the codebase led to a speed up of the shipping of this particular feature… Which is very hard to do. No business really wants you to do that.

[01:08:32.21] But what I will agree with in your analogy, Kris, is that you should be cleaning your pots and pans as you go. Never assume you’re gonna get a kitchen makeover… To stick with that analogy. Never assume you’re gonna get a makeover and you can just blow away the West wing of the house, and you’ve got a new kitchen. You’d better keep scrubbing your pans and keeping things tidy as you Go, because chances are you’re not gonna get to do it over again. It is way too costly for the business… At least in my experience, that’s what I’ve seen.

I will absolutely let Kris rebut this, but as someone who is purely on the business side, as a product manager, I take issue with that blanket statement. We on the business side do care about that. I would say we do have to weight up tech debt in conjunction with feature projects, with other priorities, but it is definitely in the list of priorities, and it’s definitely on our mind… Because if I as a product manager go to my team and I say “Okay, great, we need to build this machine learning personalized push mechanism”, and then they come back and they say “I don’t even know where we built that. We have these three microservices that are all linked together, and they’re relying on each other, and we’d have to decouple those, and build this…”

I just want a clean architecture, that we can build great features on top of… And part of that is me as a product manager fighting against the other business partners to find the time to say “No, we’re not gonna develop this feature. Our engineers need to do this cleanup.”

Agreed, you’re not gonna be ever in a position (I doubt) where someone like me will come to you and say “Hi. You have five months to rewrite your entire codebase and make it beautiful”, but it’s about bringing in those opportunities, and hopefully, if you have a big enough team, concurrently allowing your engineers to take on tech debt, as well as pushing forward features, and giving them kind of best of both worlds.

That is what I strive to do… It’s very difficult, but I would say a blanket statement that we on the business side don’t care, I take issue with. I’ll pass the baton to Kris…

Hey, you asked for unpopular… [laughter]

I agree with you on one point. I don’t think that we can afford the time to stop and have an eight-month review of a whole codebase to make sure everything spick and span and shiny. I don’t think that’s good. I think the thing that we want to do is over time do it. Over time, we’ve basically rewritten the whole codebase every year, but we don’t have any point in time where we stop doing everything and rewrite the whole thing.

I would use the analogy of rearranging your kitchen over time, and sometimes you’re just like “Okay, this cabinet is really messy, and you’re not gonna demo your whole kitchen and build a new kitchen just because one cabinet is messy… But you’re like “Okay, I’m gonna focus on this cabinet and really think about how I use the things in it and arrange it so it’s good.” And then I’m gonna do that periodically for all of the cabinets in my kitchen, just to make sure that things are where I use them, and they’re in a good space for me if I’m doing a lot of cooking. You probably don’t need to do that if you’re not doing a lot of cooking, but if you’re doing a lot of cooking, having things that you need really nearby can actually speed up the process a lot.

So I think that there is this big value proposition in this having cleanlier codebases, that you can just start adding in features much more quickly, as long as you make sure you’re continually keeping your codebase clean and keeping it consistent.

[01:12:15.15] So I guess I do agree with you on the “No, we can’t just stop and rewrite the codebase for five months.” Although I will say that that is actually what tends to happen a lot at companies. The codebase gets so bad that we declare it legacy, and then we say “We’re just gonna go build the whole thing again.” So your unpopular opinion is actually what we tend to do, at a lot of companies… [laughter]

These unpopular opinions is definitely what – like, if somebody graduates college and learns all these things, and then goes to a company, I feel like it’s newgrads that very consistently are like “All this code doesn’t follow standards and doesn’t follow these rules. We need to just get rid of it and rewrite it.” And I think a lot of it is that naivety that you can just stop and rewrite everything…

You’re right, Kris, you can definitely remodel your kitchen piece by piece. The biggest downside to that is that you have to do it within the constraints that are there. The best example I can give is – like, let’s say you have a refrigerator that’s giving you issues and you need to swap it out. You don’t renovate the entire kitchen for that, but you do have to get a fridge that fits in the space you have. You can’t just go buy this massive fridge that would solve all your problems because you want to, because you’ve got a limited space in your kitchen.

I think that same analogy works where teams need to be refactoring things and iterating on them as they go, but they need to keep it within the scope of what’s reasonable for the project. You can’t always write it the way you would if you were working from scratch, but you can definitely improve on what’s there.

I don’t think y’all have been part of a kitchen remodel… [laughter] Because you can’t take out just –

You can replace appliances…

If I tell my wife, “Look, we’re gonna redo the kitchen. We’re gonna take a modular approach. A very sensible, responsible approach. I’m just gonna take this row of cabinets and we’re gonna swap out just this row. We’re gonna leave the bottom row… It’s gonna look a little rough for a couple of weeks… Maybe a couple of months, who knows. We’re really being responsible here, because we wanna make food faster”, or whatever. That’s not gonna fly…

Some jobs, if you’re gonna replace the cabinets, you have to replace all of the cabinets, because you’re gonna bring people in to do that labor, taking out the old, putting in the new… So the analogy here being that some parts of your codebase – I think to some degree we’ve all been a part of these projects whereby somebody goes and says “Well, you know what - we should really take out this whole module, this whole component… We should just rip that one out.” And then you go in there and you realize, “Oh, crap, that one is tied to that component… So if we remove that one, we need to refactor this dependency here, which is gonna cause this one to change, and that’s gonna affect that one and that one and that one…” All of a sudden, your “Let me just refactor/remove/recreate this one thing” turns into a much larger project than you anticipated, leaving folks like Angelica to have to fight with the business to get that team the time that they need to actually do this surgical work… Which is why I think you tend to see less and less appetite from the business to let these things fly. It ends up having to be a fight every time.

Which goes back to the original around needing to have a clear plan before you start coding. [laughter]

Right… Nice tie-in.

Let’s plan it out, let’s do a tech brief, an RC, a POC, let’s get all our ducks in a row before we start building it.

And to clarify a little bit - when I was talking about the cabinets, I was talking about the things in the cabinets, not the cabinets themselves… So rearranging all of your spices, and whatnot, so that they’re easily accessible… Because yeah, a piecemeal replacement of cabinets - no. No. Why would you do that? Your kitchen would look ugly.

[01:16:08.00] You can do partial things though… To give you an example, Johnny - my brother recently painted all of his cabinets, and it looks a hundred times better. And he’s not completely renovating, but he did do something small.

Lipstick on a pig, yeah. I get it.

And you can take appliances out and swap those. But even going to your point, sometimes when you say “We’re gonna do all the cabinets at once”, the reason you do that is because you analyze the pros and cons of doing it all at once versus piecemeal, and you realize that cost-wise it’s gonna be way more effective to do it all at once. And I think with software it’s the same thing - you kind of need to figure out what’s the most effective route forward, or “Can we repaint these and get by for another five years and see how it goes?” And that’s kind of like the cleaning up. Still in my mind that’s cleaning up. It’s not forcing a complete rewrite of something, it’s just deciding what’s gonna get us by.

Fair enough.

I think the moral of this is that there’s a lot of nuance in these things… We have to apply liberal amounts of nuance to anything that we try to analogize or add in general.

The business side does care. [laughs]

I mean, I feel like half of this episode is now about kitchens…

I will say, I have never run into a product manager that has ever said “No, you’re not allowed to play down technical debt” or “You’re not allowed to make the codebase look better.” It’s always “Alright, how much time do you need? What do you think the velocity of the features we’re gonna get after it? Do you think we can still build features while we’re doing it?” I’ve never heard anybody just be like, “Hm… No. You can’t. We don’t have time to clean up the code.” Because I think everybody does know on some level that – I think they’ve all had an experience that “If we don’t clean up this code, then it’s gonna take ten times longer for me to get a single, easy, basic feature, and it is going to suck. And I’m gonna have to explain to the business why a two-week project is taking 2,5 years to complete.”

And you can always refactor as you go. You don’t even have to get permission in a lot of cases. It’s just if you’re touching some code and the code around it could use a clean-up, you can sometimes get away with it.

Yeah.

Well, I said I can, but I don’t have a boss yelling at me, so… Maybe I’m different. [laughter] Maybe it’s been too long.

I am very happy if an engineer comes to me…

If anybody has a boss yelling at them, they need to change that situation… That’s what I’m gonna say.

Psychological safety.

If any engineer comes to me and does a small change and they’re like “Well, I was just doing this small change. I put unit tests in, I did some cleanup.” I’m like “Thank you. You’re wonderful. Please continue.”

I mean, Johnny, didn’t you know that’s what pair-program with Mat is like? He just yells at you the whole time. [laughter]

Just getting yelled at… [laughter]

No, I’m just kidding. I have no idea, but I’ll try and let you know if that’s what he does.

Management by screaming is not the type of environment most of us want to work in.

Alright, I think we’re over on time. Thank you everybody for joining us. We hope this has been enlightening and helpful, and hopefully you’ll take some time to learn about writing. I guess, as we’re signing off, Kris, Angelica, Johnny - do any of you have any recommendations on what people can look up to learn more about writing? Any books or anything you recommend, that might apply here and help them in their coding world? Didn’t mean to put you on the spot.

I mean, honestly, if you’re interested in the concept of “coding is writing” and it’s a way of communicating your thoughts and feelings, and communicating what you’re trying to do to other people - if you’re interested in that concept, I would recommend that you watch Lera Boroditsky YouTube talk. She did a TED talk about how language shapes the way we think, and kind of cognitive diversity when you’re using different languages… I think code does kind of come into this. And how it’s interesting that languages at their root are all very similar - they have the same baseline - but then the way in which you communicate to others tells a lot about yourself and the way in which you think about solving problems.

So I think it’s interesting, it’s tangential to a lot of the points we’ve made here, but I think it’s a good talk. Check it out.

[01:20:11.28] If I can pitch something I did… I did a talk at GopherCon in 2019 called “The gopher’s manual of style” that hits on a lot of these same points and kind of extrapolates on them, and goes in a little bit of a different direction. It’s on YouTube.

Scratch that. Just watch Kris’ talk. [laughter]

We’ll have links in the show notes, so if you go to The Changelog website, you’ll be able to get those.

My recommendation is - since this is a Go podcast, and we wanna tie today’s topic to Go, I’d say if you haven’t read Effective Go, read Effective Go. It’s one of the things I tell people that I read once a year… And reading how the creators of the language intended for it to be used, you’re gonna pick a lot of how to communicate intent in your code by reading that manual.

Also, there is a – we’ll put it in the show notes, but there is something that the Go team had put together, a style guide (we’ll put that in the show notes) for the do’s and don’ts for code review comments… If you search up “golang code review comments” you’ll find it. That also is a very good piece of documentation to read in order to help you with the writing.

But the thing about writing - it’s one of those skills, just like coding; it’s just something that you’re gonna have to do… So write. If you don’t have a blog, if you don’t have opportunities to write at work, seek out those opportunities. If you don’t have those at work, or it’s not possible to get those at work, write a blog. Write what you’re learning, how you’re learning it. Again, get in the habit of writing for others to consume, not just for you.

And again, you don’t have to take people’s judgments of that. The internet is not always friendly. You might have people say “Well, I hate that”, and that’s fine, too. You’re not doing it really for them; you’re making your work public, but this is really for helping you. This is gonna require a little bit of stepping out of your comfort zone. And before you call me out and say “Well, Johnny, where is your blog?”, I don’t blog. I do a ton of writing for either my job, or for training courses or whatever it is, so I’m getting my writing kicks in other places, so don’t call me out on that.

But again, just find an opportunity to get some writing experience, basically… I guess that’s the bottom line. Do it, and hopefully it gets better over time.

I would add a small thing to that, too. I think a good way to jump into writing more, that is a little bit less of a jump as blogging is, is to do journaling. I think just like getting yourself in the habit of taking your thoughts and transforming them into words, and seeing how that feels, and kind of get a feeling for that, is a really great way to start becoming a better writer.

I think it was – who was it…? Richard Feynman, I think, had that quote about – a reporter was like “It’s so nice that you’ve documented your thoughts like this”, and he’s like “No, no, no. This writing - these ARE my thoughts. I think through writing.” And I think I feel very similarly about that. When I’m writing, it’s not like I think and then I write; I write by thinking. And I think that’s a very effective way to become a better writer. I think a big part of it is just doing the craft. If you wanna be a writer, start writing.