communication for developers - estimates code reviews and other hard problems

src: Communication for Developers: estimates, code reviews, and other hard problems by Voytek Pituła - 2024-03-13

Abstract

Shannon communication model:

sender -> encoder -- channel --> decoder -> receiver
what you want to say -> what you say -> what they hear -> what they understand

The communication goal is to have what you want to say == what they understand.

Communication in estimates

Most important question: why do you need estimates? You can’t communicate effectively without understanding the other side.

What to explicitly mention

When estimating a release date:

• scope: what will be released an to whom
• num of dev-days: how much work-time it will take
• uncertainty factor: how confident we are about the work
• assumed dev assignment: how many devs will work on this
• assumed dev availability: how much time a single dev can devote
• end result: what will be delivered
• final date: by what date we expect the release

Example:

Quote

• ~55 man days of work
• uncertainty factor: 1.2 (domain is well known but provider is new)
• 4 work days a week (as usual, meeting and operations taken out)
• 1 dev
• 55 * 1.2 / 4 = 16.5 weeks = ~4 months = 1st December Usual disclaimer: closer we get to that date, the more precise the estimate will be.

Estimate vs commitment

Be clear:

• estimate = prediction
• commitment = promise

Code comments

It’s a message into the future.

Humor is valuable!

Error messages

Another message into the future.

Tips

• Leave breadcrumbs behind: pieces of context that will help in future investigations.
• Build in the open: you can never know who might be interested, who might be affected, and if it’s not you who misses some context.
• Keep people in the loop.
• Coordinating releases:
  • It can be really complicated, when multiple parties are involved (mobile, backend, marketing, legacl, …).
  • release != deployment
  • Threads & emojis can be enough

Pull requests

Author

• Find reviewers:
  • Concrete people, not groups.
  • As many as you need, but not more.
  • Diffusion of responsibility: the greater the number of bystanders, the less likely it is that any one of them will help.
• Put a deadline: explicit date by which you want to merge.
• Make it reviewer-friendly.
• Make it small.
  • If not possible:
    • description: what the PR is about
    • highlights: the most important places to look at
    • remaining TODOs: to know what is not done yet
• Don’t force-push, the reviewer won’t know.

Reviewer

• The LOGAF (Level Of Give A Fuck) scale.
  • Not all comment are equally important.
• Use conventional comments.
• Don’t be a jerk.
  • Propose solutions (e.g. new names).
  • Offer help (e.g. pair programming).
  • Show empathy (e.g. no one wants to fix stuff ad infinitum).
  • Pick your battles (not every issue is important, perfect doesn’t exist).

Everyday communication

• Don’t just “hello” in asynchronous communication.
• Repeat, repeat, repeat: people will forget, miss messages or misinterpret. This is normal.
• How to get a response?
  • Target your messages.
    • No explicit @mention ⇒ no response.
    • Ping someone even if you’re not sure if they can help.
  • Explain why you need something.
  • Explain when you need it.
• Give the responses you want to get.
  • If you don’t know the answer bu you know someone who might, ping them.
  • If you don’t have time, say this.
  • If you plan to look at it later on, say this.
  • If you started looking
• Adjust the tone.
  • Over-enthusiasm can be worse than grumpiness.
  • Don’t be a pushover: some messages need to be harsh.
• Adjust the formatting.
  • Messages should be easy to scan.
  • People are busy, most of them won’t read a wall of text.
  • Put a TLDR at the top.
  • Bolden the essence.
  • Use bullet points.
  • Don’t over-do it.
• Call or message:
  • Meetings are costly, inconvenient, annoying. And effective.
  • Threads with more than 10 messages sent in an hour should be a call.
• Be gentle with @pings.
  • Use as little as possible not less.
  • When pinging from long thread, summarize, don’t be a jerk.

Principles

• Understand.
  • Try to think why the question is being asked.
  • Don’t take the message at face value (but sometimes do).
• Ensure the message was understood.
  • Don’t stop at saying what you want, make sure the audience got it.
  • Don’t be the UDP.
• Adjust to the audience.
  • Try to imagine how your message will be received.
• Don’t be a jerk.
  • Formalities, conventions, smiles matter.
• Language proficiency is less important than you think.
  • Sophisticated language is an enemy of efficient communication.
• Brevity matters.
  • The shorter the message, the bigger the chance it will be read in full.
  • Where brevity matters the most: in code comments, in documentation.
• Communication in the open.
  • It’s easier to ignore a message than to become a telepath.
• Effective communication is hard and costly. It’s not always worth the effort.