How We Talk About Code: What We Say & What They Hear

As engineers, code is the product we’re paid to produce. A lot of energy goes into writing it well, maintaining it, testing it. These are good things to spend energy on, and on the way there, we also spend a lot of time talking about code.

And I think it’s important to put care into how we do that well too. I’ve seen how people talk about code in ways both deeply hurtful and profoundly empowering. So how do we avoid the former and do more of the latter?

Neither of the examples below are rooted in a single specific example, but from the small things I’ve seen myself and the conversations I’ve had with hundreds of other devs, both very fresh and those with years of experience under their belts.

I’ll say this again at the end, but I want to start here too: There will never not be constraints or imperfections. Let’s build things anyway, and build our teams up as we go. 💙

Every developer I know has one of these stories: the tale of that one piece of code that someone who used to work at the company wrote, that no one wants to touch. It’s convoluted, it’s untested, poorly designed. Who knows — for whatever reason, it’s bad.

And they’re not shy about saying so.

And I get it. There’s camaraderie in laughing about bad code, in trying to avoid picking up the ticket in that piece of code no one wants to touch.

And there’s another side to this too: the people who still work there. Maybe they’re working on a piece of code right now that they’re not particularly proud of because of some constraint that’s out of their hands. And what they’re hearing in that conversation is how the team is going to be talking about them a year or two from now. A team that’s done it once will do it again.

There’s camaraderie in so many things that don’t involve tearing someone down (even if they’re not there to hear it). Let’s focus on those. Solving problems. Learning how to do things better than we knew how to do them before? Building our own skills and those of our teammates. Laughing about that rabbit hole we spent days stuck in, only to dig our way out together.

Here’s another story I’ve both seen and heard many times over:

A dev starts a new job. Maybe in this story you’re the one who’s onboarding the new dev, showing them around the code and answering their questions. Or maybe you are the new dev. Either way.

The new dev starts, and as they’re learning their way around the codebase, they notice tech debt. Maybe a lot, maybe a little — every codebase has some.

They ask why a lot (tone and phrasing and context matters a lot in these situations - a “why” can be asked with curiosity or with derision — I’m not suggesting people stop asking why!). Maybe they get distracted from their work and suggest tearing things out, redoing them. Better this time.

Here’s the thing about tech debt:

No one sets out to create it. There’s always a reason.

Sometimes it’s because someone who’s just not a very good engineer wrote it. But I think that’s exceedingly rare. Usually it’s because there were things about the future that, while they might seem obvious now, (now that we’re in the future) were not obvious at the time. Or perhaps the project was on a tight budget or timeline, so some corners had to be cut, and these decisions were intentional, if undesired.

Either way - there were reasons, and they are probably not ineptitude, and are almost certainly not malintent.

So it’s on us as the new dev to ask our questions with curiosity, to make better what we can and leave the rest for another day.

And it’s on us as the tenured team member with context to recognize the value our new teammates are providing in raising concerns about things we may have forgotten to notice because it’s become so normal, and to answer their questions about why without getting defensive.

This phrase, this idea, are not mine — someone I work with gave me this advice, after learning it the hard way themself. But it feels so relevant to this conversation.

The idea is this:

  • Acknowledge frustrations with technical debt.

  • Acknowledge code that needs to be improved.

  • Acknowledge code that needs to be deleted.

  • Acknowledge data models that don’t line up with their use case or the real world.

But don’t commiserate, grumble with them about how bad it is, how much you would’ve loved to delete it, rewrite it to, if only it hadn’t been for . This is especially true for senior engineers. We set the tone for how a team talks about their work and their codebase, and commiseration can lead a team down a path of negativity and victimhood, instead of empowering them to work within their current constraints, continuing to build a product within them, and make things better as they are able. This is all we want to do as engineers. There will never not be constraints or imperfections. Let’s build things anyway, and build our teams up as we go.