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.

Comments

Post a Comment

Popular posts from this blog

Crossing the Rubycon

I first learned Ruby about a year ago and it quickly became my scripting language of choice; a position I doubt it will ever lose, hence the name of this blog post. Here are some of the reasons that I prefer Ruby over Python, NodeJS, and PHP, for most use cases. Testing The primary reason I prefer Ruby is how great writing tests is. Tests in ruby can be incredibly concise and natural. The built in mocking, stubbing, and monkey-patching functionality is very powerful. I particularly love the way contexts can be built up with let(:...) to have very descriptive and concise tests. The philosophy If you look at a language like PHP, it has basically no philosophy behind it, at least not a consistent one. Hence you end up with all sorts of weird behaviors. For example, consider preg_match , which finds matches of a Regex in a string: preg_match() returns 1 if the pattern matches given subject, 0 if it does not, or false on failure. Gross .  Wait, where are the results of the regex match? // 
Read more

The many benefits of working in small increments

If you're a software engineer, you've likely heard of the Single Responsibility Principle  (SRP). I believe it's the single most important principle in software engineering. The simple explanation is that one object should do only one thing and do it well. Having a well defined single responsibility makes code easier to understand, change, delete, and test. The complexity of code grows exponentially with size. Two 100 line classes, with proper segregation of responsibility, are significantly easier to understand than a single 200 line one. SRP is the "work in small increments" principle for code, and the same exponential growth in complexity applies to much more than just code. Working in small increments shortens the feedback cycle, which is the best thing any organization can do to increase its velocity. Small Tasks Every task should be small - small enough to complete in less than two weeks, ideally less than two days. Small tasks are easier to write, understan
Read more

The two qualities of great software architecture

Great software architecture solves a present business need and is easy to change when business needs change. Software architects have developed a number of heuristics: patterns and principles that help to achieve these goals. A software engineer that applies but does not fully understand these heuristics may implement them in situations that run counter to the goal. To write great software, it's important to understand how each pattern and principle contributes to the goal. Entire books have been written on most of these subjects. This is intended to be a brief overview, not an exhaustive list or explanation.  Solving a present business need Most users could look at an application and tell you whether it solves a present business need, aside from some of the more subtle nuances. For example, an application may solve one need but is not secure, which is usually one of the business requirements. Some of the criteria that may roll up to this metric, depending on your business: User ex
Read more