How to be a better communicator as a software engineer

Communication is one of the most important skills as a software engineer, and one of the hardest to improve. Engineers frequently provide recommendations on improvements for "hard" skills, e.g. through code review, but rarely do for "soft" skills. It takes a lot of self-reflection and practice to improve the soft skills.

Code is a form of communication

“Programs are meant to be read by humans and only incidentally for computers to execute.” - Donald Knuth

The most common form of communication used by software engineers is code. Code communicates intentions to peers and future maintainers. Code is read far more than it is written. Next time you go to write new code or refactor old code, consider how much time you spend reading existing code before writing the new code. When you're writing code, remember the tax that other maintainers are going to have to pay every time they read it. Write code that is easy to read, and easy to replace. There are a few ways to improve the way your code communicates your intentions:

  1. Make sure you use clear variable, method, and class names. It is worth spending significant time on this. Don't just pick the first thing that pops into your head. Think about the business reason behind everything, and name according to that business reason.
  2. Follow SOLID and DRY principles. It helps reduce cognitive overhead for someone reading through your code, because they can easily find and change the parts of it that are relevant to what they are working on.
  3. Communicate the reason behind complex business decisions in comments. Remember: code tells you how, comments tell you why.
  4. Document what needs documenting. Code documentation comes in many forms: documents describing technical decisions/architecture, API documentation, code comments, etc.

Code reviews

Code reviews are a critical medium of communication for engineers. It is an opportunity to share knowledge, tips, praise, and constructive criticism. Remember that code reviews are about the code, not about the author. Don't be afraid to give and receive constructive criticism. Software engineering is a very difficult process, and no one completely understands all of the trade-offs. Be grateful when someone shares a different understanding of the trade-offs than you have, even if you don't fully understand/agree with their understanding. Be careful not to overuse text-based communication as your primary form of code review. For complex tasks that have far-reaching implications, it's often worth opening up a video chat and discussing more deeply.

Non-engineering communication

Another very common form of communication by engineers is cross-functional (XFN) communication with non-engineers: PMs, designers, customers, and business stakeholders. All of these are important to fully leverage. One thing that often separates a mid-level engineer from a senior, or a senior from a staff/manager, is this form of communication. It becomes a critical skill at senior engineer in most companies, since the senior engineer is typically expected to lead a team or project. This is something that rarely gets better without practice, so find and ask for opportunities to practice.

Speak in terms of business value. Make sure everyone understands why before how. Leave technical details at a minimum, unless asked to explain more deeply. For example, the following is not ideal for most XFN groups: "we have decided to refactor into a new microservice, so we don't have time for this right now." This version is better: "we are working on some improvements that will reduce our development time for new features, which we hope to complete by Q1. Can this wait until then, or is it urgent?"

Practice nemawashi, a Japanese technique for organizational alignment. The simple form of this is: if you're going to propose a significant change, don't do so for the first time in a presentation or meeting. Instead, let people know in advance with 1:1 communication. Then hold the meeting after you've gathered feedback, honed the idea, and gotten everyone aligned on the general concept.

Ask your manager and peers for feedback

It's very difficult to know what areas to focus on improving without feedback, because your weakest areas are often your blind spots. One of the best ways to find your blind spots is to ask people you work directly with what they think about your communication. Be vocal about your desire for constructive criticism, as most people are cautious about sharing it. Show gratitude for every piece of criticism you receive, otherwise people will be reluctant to share more. A good place to request feedback is in performance reviews so that feedback can be shared anonymously and curated by your manager. You can let people know ahead of time what areas you want specific feedback on.

I've received very helpful feedback on my blind spots through this process. For example, I was told by one manager that as a tech lead I was too prescriptive about certain solutions. This was likely leading to teammates being less willing to speak up about alternatives. I switched from defaulting to sharing my opinions to instead asking questions, and only steering the team when I had to. I noticed an immediate increase in team participation, and better results from the team overall.

I was told by another manager when I had recently joined a new company that my insistence on sharing my opinions on just about everything was comparable to a bull in a china shop. My immediate instinct was to go on the defensive. After fighting that instinct and thinking critically, I could see clearly what he meant. To date, this is some of the best feedback I've received, and it is something I'm still trying to improve on. One helpful piece of EQ advice I've found on this was the 3 question rule. We're often taught as engineers to share opinions and feedback with the team. The challenge is to not go overboard with this - it's important that the most vocal people don't drown out the quiet ones. It's the people who listen most and talk the least that often have the most useful things to say.

Practice presentations

For me, one very important part of improving my communication was just getting more comfortable with it. One of the best ways to get more comfortable with communication is to host presentations. Seek out opportunities to host feature demos, share knowledge, or make proposals. Being a good presenter is a great skill to have and improves other communication skills as well.


Popular posts from this blog

Crossing the Rubycon

The many benefits of working in small increments

Feature design process