The Developer Communication Handbook

From code review comments to handing in your notice

Communicating with people comes naturally to most of us and usually works, so we don’t think about it too much. It’s also a vague and unfalsifiable topic, which is the opposite of what technical people enjoy. As a result, few of us think about improving that skill, often to the detriment of our colleagues, teams and companies. This handbook tries to help with that by focusing on the parts of communication that matter to software developers. It isn’t a comprehensive guide, and won’t, for example, teach an engineering manager how to lay people off, or how to tell your kids that their kitten has died. But it does try to teach how to:

and much, much more, including a few general things like: how to ask questions, cross cultures, not be a (total) jerk, and speak to a wider audience.

There is one perfect, infallible way to communicate without any friction: know what’s inside the receiver’s head and send your thoughts straight into it. Unfortunately, evolution never granted us that perk, so we need books like this one.

And so every piece of advice in this handbook distills down to two moves:

The whole of this book looks into different aspects of software development from those two angles: how to better understand people we talk with and how to adjust our communication so they hear exactly what we wanted to say.

Before the first line of code is written, a project exists as words alone. And words mean misunderstandings, which are easy to create but also easy to fix. This part covers the conversations and messages that happen before coding starts.

To deliver a product or a feature we have to know what the requirements are. The lucky among us have a product manager or a business analyst who makes this process simpler, but even then a significant amount of work has to be put into refining their vision. Alternatively (or in parallel), we need to talk directly with stakeholders (most of whom will be non-technical) and figure out the requirements on our own. In either case there is a lot of talking involved and it’s important to do it effectively: extract as much correct information as possible in as little time as possible (because who likes spending time in meetings?). And do it so the other side will want to talk to us again.

As a software developer you will be asked for estimates constantly, whether you like it or not. It may not look like a communication problem at first, but consider: you say “about a week”, meaning the coding effort on the happy path, and the asker hears “live in production for everyone, next Friday”. The number was fine, but its meaning got lost on the way. A good estimate is a number that means the same thing on both sides.

Below is an example of what an estimation message could look like.

Backend estimate for the payment-provider integration

That is one week past the 15th August deadline. We will be delivering in small increments, so by the 15th everything except a part of the withdrawal flow should be in production. Hitting the full deadline is possible but not likely.

The estimate covers development, testing on staging and integration with the provider’s sandbox. Going to production might add time for non-dev activities (e.g. compliance sign-off), which we can’t predict. Not included: spending limits and automatic conversions, both out of scope for the MVP.

Usual disclaimer: the closer we get to the date, the more precise the estimate will be.

We write a technical design (we do, right?) to communicate our intent to build something: the vision, context and justification for the decisions taken. In return we expect others to poke holes in it while it’s still only words and cheap to change. Here we cover only the delivery side of this problem (for the content you’ll have to look into other resources).

See also Getting a PR review and Providing a PR review, as some of the advice there applies to technical designs as well — including how to get the doc actually reviewed instead of published and forgotten.

This section is a bit special, as it leans heavily on persuasion and politics and isn’t really specific to developers. Still, I’ve too often seen developers struggle to get approval for things like automation, tech-debt reduction or adopting a new library or pattern. So it’s here to help, and to limit the frustration and learned helplessness.

We should migrate off the legacy queue, the code is a mess and nobody wants to touch it.

Migrating off the legacy queue should cut our on-call pages by about a third (most of them trace back to it) and speed up every checkout change we have planned for Q3. We can do it incrementally, one consumer at a time, and stop halfway with no harm done. And we’ll be in that code anyway for the upcoming SMS notifications.

The first asks the decider to care about your pain. The second speaks their language — fewer incidents, faster delivery — and makes the bet safe.

This part covers the communication that happens while the features are being developed (the so-called “real work”), from code constructs to stakeholder interactions and work visibility.

We start with the messages that live in the code itself: comments, error messages, log lines and names. Your first instinct might be to reject the idea that any of this belongs to communication at all, but I hope to change your mind by the end of this section.

A comment is a message to someone reading your code in the future. That someone has none of your context and a different set of knowledge and goals. That someone might as well be you in two years. So how do you write to a person you know nothing about?

The general advice here is to imagine what information might be needed by someone reading the code 5 years from now and provide it.

Here is the same comment written in two ways.

// The provider drops idle connections after ~30s, so the first call after a quiet period almost always fails (PAY-1421).

The first repeats what the line below it already says. The second records the why, which is the only part a reader can’t recover from the code itself.

Like a comment, an error message is a message into the future, except that the communication is about something that didn’t go well. What’s worse, you can assume even less about the reader: with a comment it was most likely a developer, while here it might be a developer, a support agent, an SRE or the user who triggered it.

Here is the same error message done in two different ways.

Can’t update the address of an inactive user. Reactivate the account from the user’s main screen first, then try again. [ADDR-409]

The first is true and completely useless. The second says what failed, what to do about it, and hands the reader something they can paste into a support ticket.

A log line completes the trio of messages into the future: a comment explains the code, an error explains the problem, and a log line explains what happened.

Here is the same event logged in two different ways.

ERROR Failed to send email to [email protected]! Will retry.

INFO email send failed, retry scheduled kind=weekly_digest user_id=u_1029 provider=mailgun error=connection_timeout attempt=2 max_attempts=5

The first shouts ERROR about something that will most likely fix itself, and leaks an email address. The second is quieter, greppable, and says what happens next.

A name is a small message to the person who reads the code next. It will be read far more often than written and has to survive years or decades. And depending on the scope — a local symbol versus a whole service — it can be one of the highest-impact messages you ever write.

Docs are a way to move the knowledge from your head to other people, most of whom you will never meet. But those docs are also a liability, the same way the code is — every documentation page has to be kept up-to-date or it turns into a trap. The art is writing as little as you can get away with, but enough to solve the real problems that arise from the lack of it. This section is about how much to write and where to put it — for the what to write side, you can start with Diátaxis.

Getting your code reviewed in a timely and thorough way is primarily the author’s job, even though it is someone else doing the reading. Most of it comes down to lowering the effort you ask of the people whose attention you need.

Here is the same request for review made badly and well:

@Paolo @Ezequiel, could you look into this PR for improved tracing in the fiat-service? I’d like to merge it by Thursday morning.

The first is addressed to nobody in particular and gives no reason to bother. The second names two people, says what the change is for and when it needs to land.

On the other side of the review, the roles reverse: now your comments potentially block or help someone else (or make them depressed and burnt out). A good review catches problems (that matter) without making an enemy of the author.

Here is the same review comment in two versions:

This is wrong, don’t pass a raw string here.

issue (blocking): passing the raw string skips the validation that UserId does on construction. Could we parse it at the boundary instead? Happy to pair on it if the change spreads too far.

The first says the author is wrong and leaves them to work out why. The second explains the problem and offers a way out, with a label that says up front how much it matters.

One day your work has to be explained to someone who doesn’t write or even read code, like a product manager, a support agent or your grandma. In such cases you have to become a translator from technicalese to legalese, accountinglese and other dialects that resemble English only on the surface. (The other direction — extracting information from them — is covered in Extracting requirements.)

Here is the same status update to a non-technical stakeholder in two versions:

The PR for the idempotency keys is merged, just waiting on the migration to run in prod.

The duplicate-charge fix is done and should be live for customers on Tuesday.

The first is accurate and means nothing to the person waiting on it. The second drops every word they’d have to translate and answers what they came for: is it fixed, and when do customers get it.

Most of your work becomes visible only when you share it. Plenty of solid engineers stay underappreciated simply because nobody sees what they do — this section is about not being one of them.

You might want to use an existing format for sharing your work. A 5-15 report is a weekly update designed to take 15 minutes to write and 5 to read. Or borrow a team-wide practice like a demo Friday, or a #shipped channel.

The previous parts followed a project through its stages. Here we step outside that timeline and look at the messages, pings and calls that fill every working day, whatever stage you are at. None of it is hard on its own, but it adds up: your message is one of the hundred the receiver will see today, and small habits decide whether it lands or gets lost.

Asking a colleague for something looks too simple to get wrong, yet you’ve probably seen a question go unanswered more than once. Your question competes with everything else in the receiver’s inbox, and whether the answer arrives immediately or never is largely decided by how the question was written. Some of the fixes below cost no more than one extra sentence.

Here is the same question asked in two ways:

Hey, I need to get CPU usage of our servers. Not sure who can help with this, maybe @tiago? We are releasing a CPU-heavy feature on Wednesday and I need to prepare the setup.

The second names a person, states the actual goal and explains why the answer is needed by Wednesday. The first looks cheaper to write, but it opens a slow guessing game: whoever answers doesn’t know it’s urgent, and “where can I find metrics” might not even be the right question for preparing a release.

Once you know what to say, there is still the matter of