This is an opinion piece.
I usually write about technical subjects but I recently wanted to formalize my opinion on the role of the software engineer and decided to publish it in the hope it could benefit some readers or trigger interesting discussions.
TLDR;
You have two jobs:
Writing good code is the easy part; it has challenges of course but most engineers struggle with the second part. That’s what I’ll be talking about.
There’s a famous quote attributed to Phil Karlton:
There are only two hard things in Computer Science: cache invalidation and naming things.
That quote is certainly true while purely discussing software engineering but if we expand to areas that use computer science, it’s clear that communication wins as the hardest part.
Let’s try to illustrate that point with some examples.
Reviewing someone’s work is a personal process, and criticism, whether it’s constructive or not, can be difficult to digest. But it’s not just about practicing good “etiquette”—this is the easy part.
It’s also important to convey intention and adapt to your audience. Let’s imagine a scenario with Junior Billy writing some code and Senior Bob doing a review using the following code:
if ok {
return 32
} else {
return 36
}Senior Bob: These numbers are a bit puzzling! And to which Junior Bob replies with the updated code:
if ok {
return "OK"
} else {
return "NOT_OK"
}And a whole bunch of updates everywhere the function was called.
Was it necessary? Maybe. Was it needed for this PR? Probably not.
Senior Bob could have replied with:
Senior Bob: These numbers are a bit puzzling. Maybe to make it a bit clearer you could introduce either a named variable to convey the meaning in this function or a constant to be used elsewhere in the code at a later stage or in a follow-up PR if you have the time.
Senior Bob could even give a code example; it would cost him less than a minute and would help Junior Bob grow and not lose hour(s) of his/her time on a wrong rewrite.
Going the extra mile in code reviews always pays and is another example where making sure everyone is on the same page is beneficial.
Note: Some people like to use an Emoji legend to convey intention. This is especially useful when you or the person being reviewed have not completely mastered the language you’re doing the review in. In this case, codifying intention is a good approach to avoid misunderstandings.
A lot of things can go wrong in a meeting, so communication is key here. I won’t create a list of all the mistakes we, as developers, make. Instead, let’s focus on three points I see a lot of people struggling with:
The importance of identifying the target audience is true for all kinds of meetings. But as developers, we have to learn to simplify concepts and keep things simple.
The next time you are in a meeting, take a step back and put yourself in the other person’s shoes. Think about how someone with no technical knowledge would perceive the information you are about to share with them.
🙅♂️ Don’t say, “This will probably raise the mean time by 2000ms for the whole website because the transaction will generate a table lock.”
👍 Say, “This is going to lead to a significant performance issue, which could slow down the system.”
This comes with some practice but you can practice with your spouse, friends, and family. This is key to being an effective communicator.
You can and probably should still teach your non-tech coworkers some “crucial” tech terms and, in some companies it is part of the company glossary or part of the onboarding (terms like “front-end”, “backend”, “iterate” or “mvp”, for example). Similarly developers should probably learn some business vocabulary to understand their coworkers’ jobs and challenges like “churn” or “ltv”.
This may sound ridiculous to some but communication is not just about presenting ideas. Careful listening requires energy and can be difficult and, in certain situations, boring or unpleasant, that doesn’t mean you can’t do it.
Avoid multitasking even if you can multitask or think you can.
Be patient and hold your tongue.
And try to interpret what’s being said.
Based on the purpose of your discussion, what the speaker cares most about, or what’s been said before, what does this mean? Use what you know to interpret what they’re trying to tell you, and ask questions if you need more details.
Rephrase your understanding if needed.
Also, assume the best. Assume that the intention of the person opposite to you is good and clever, even if you understand it at first as stupid and offensive. Again, repeat and rephrase.
Meetings would go faster if people took the time to listen.
Careful listening also applies to written communication; read twice before answering, put the message in context and don’t hesitate to ask questions before having a (strong) opinion.
Double check what you wrote before hitting send as well, disambiguation is often more painful on a written discussion.
Because of a failure to take the first two points into account, but also for countless other reasons, I have often witnessed people leaving a meeting with a different understanding of the next steps. And you might discover this days, weeks or even months later!
A good reflex is to always have a “Scribe”, someone taking notes during a meeting with a specific section for action items and their owners in the meeting notes. I also like to keep the last part of meetings to focus on the recap and the next steps:
So we only have five minutes left, let’s stop here. What are the next steps?
And enumerate each of them with the people who own them.
Sometimes, it also makes sense to repeat and rephrase something to make sure everyone has the same understanding.
Let’s imagine a scenario with Developer Jim and Product Manager Laura:
Developer Jim: It should take two days.
Product manager Laura: Alright, so it’s Tuesday, I guess it should be ready by Thursday night for a release Friday morning?
Developer Jim: Ah, no, I meant two days of full work. But Wednesday afternoon I do pair programming with Junior Billy on his assigned task and Thursday afternoon I have my performance review. I’d therefore like to avoid releasing on Friday. It should probably be released Monday morning!
Here, Laura had the right reflex by not assuming two days meant two calendar days and to make sure Laura and Jim had the same understanding of the situation.
Communication is hard but going the extra mile always pays. Communication helps to build strong and healthy relationships, so don’t underestimate its power.
Most of the difficult problems engineers face include both technical and human components, and the greatest engineers can address both.