Originally written in an internal company wiki in summer 2024-ish

On Communication

Software engineering is a communication-heavy craft. Arguably, everything we do is a form of communication; the code we write is just as much for another human to read as it is for a machine to execute. Our job as engineers is to solve problems, and in any org of size, this quickly becomes an exercise in enabling others to solve problems.

The following are some ground rules around communication that I’ve found to be generally Good PracticeTM in my time as an engineer.

Be kind.

Being kind is not being collaborative or polite or helpful. Maybe you should also be these things, but ours is a broad field and the right approach is often context dependent. Perhaps the politics of your organization are such that it is healthier to disengage with an initiative rather than champion it, or better to ignore another team’s request and focus on a higher priority.

Being kind is having a baseline level of care and respect. You are a professional with professional colleagues. You can disagree with something without attacking it. You can be blunt without being rude. Something has gone wrong when people cannot exist in an organization without making enemies.

Leave a paper trail.

You aren’t alone; you work with, at minimum, your past and future selves. They, and other more corporeally distinct people, have different context and knowledge than you do in this moment. If you’re doing something that has associated context (you are), describe that context. Your teammates, your future self, and the engineers who come after you will be better off for it.

Link tickets to PRs, put context in git commit messages, describe what you’re working on in Slack. Inevitably, someone will need to follow in your footsteps. Leave them a trail to follow.

Respect your code.

You will often find yourself in the position of working on so-called “bad code”. Maybe this is some abandoned project you were tasked with reviving, maybe it’s legacy code you have to maintain, maybe it’s something you yourself wrote in years/months/days past. Whatever the origin, this code is unpleasant to work on. It’s poorly written. It’s fragile and prone to breaking. It’s undocumented and hard to understand. The very thought of having to wade into it causes anxiety and despair. It’s tempting to start badmouthing and avoiding this code.

Resist this temptation. It is one of the subtler rots you’ll encounter in your career, but it’s as harmful as any other if allowed to spread. For better or worse, your code is your responsibility and you’re stuck with it from one day to the next. Don’t let it become your enemy. No one else will make it better, and if you lose respect for it, you won’t make it better either.

Of course it’s fine to complain or grouse about parts of your job that are difficult, code or otherwise. Just don’t let it be your default tone.

Don’t use war analogies.

War has incredible human cost. Lives are lost, people are displaced from their homes, and some of the most acute grief and horror in the human experience is felt. There’s a chance you work with someone personally impacted.

In your work as a software engineer, you are not waging a war. You are writing software. No one is dying because of your endpoint design. You’re not in a war room. You’re not fighting anybody. You’re not engaged in trench warfare.

If you find yourself making these kinds of analogies, stop.