Tips for Good Communication in Software Development Teams

Whether it is reviewing pull requests or any other form of feedback — doing it the right way, makes a world of difference

After working for about 7 years as a professional Software Developer, I have come to realize that communication is a skill as important as our technical knowledge.

We focus and spend hours and hours understanding bits and bots of that new framework “you have to learn! ”, yet we, for the most part, seldom work on communicating better with our team members.

Communication is a skill as important as our technical knowledge

Communication has an impact on people, which is why doing it right should not be an optional or a nice to have. It’s a matter that every manager should make sure that a team gets it right.

Communicating well is a skill

Some people may not believe or realize it, but in my experience, this is one of the most important reasons why some people plateau and fail to grow in their careers.

Communication is a huge topic, and as such, I want to clarify the topics discussed in this article. I won’t talk about how to communicate better for sounding a smart dude, to prepare your next big presentation, or how to market your side project better.

This article, instead, will be focused on emotional intelligence and how to apply it to the challenging situations that happen every day where communication plays a crucial part.

Why is Communication so important?

Communication is a hard thing to crack for every team: it is indeed influenced by several aspects that go way beyond coding. Before being programmers, we are humans. As such, we all have different personalities, upbringings, values, culture, and language.

Despite all the differences that may exist between team members, I feel we can find some ways that can help teams communicate and work better together.

What I mean by “Communication”

First of all, when I talk about communicating, I do not mean you should be forced to socialize, or that you should start your days talking with your colleagues about your weekend plans and a detailed list of what you did the day before.

If your colleagues are OK with that, by all means! But that’s not the point. You don’t have to be friends with your colleagues in order to be a great team member, you just need to be a decent human being.

What we want to talk about in this article is how to make sure we can communicate with our colleagues in a way that:

  • gives them the opportunity to share their point of view

  • gives them respect, regardless of seniority (or anything else)

  • is non-threatening

  • helps them, or you, improve at what we do

You don’t have to be friends with your colleagues to be a great team member, you just need to be a decent human being

Communicating during conflicts

As programmers, we engage in conversations multiple times a day in different situations and sometimes these lead to conflicts. Let’s see a few common scenarios we encounter every day and how our communication can lead to better and healthier workplaces. In my experience, a healthy workplace is also usually an efficient one.

The most difficult situations I’ve come to having to deal with in my career are definitely reviews on pull requests, which especially for junior developers, can be a very intimidating experience.

Unfortunately, this is a particular scenario that is quite evident even in some large and famous open source communities, which causes many coders to keep away from contributing to Open Source.

Why do we PR review?

The common reasons why we use reviews in the first place is:

  • catch bugs before they get shipped to the master branch

  • propose improvements and discuss changes

  • learn code you haven’t written and keep up-to-date with the codebase

In my career, though, I’ve definitely met some developers who totally missed the meaning and objective of reviewing other developer’s code, although they were a small minority.

Most of the people I worked with totally knew the concept of reviewing, but the way they did it was completely wrong. And guess what? I was totally wrong too.

In my career, I have made an enormous amount of mistakes, which only with years of experience I’ve come to realize and comprehend. Being the young kid who knows everything about the latest framework is fun and messes with your head a little bit.

After a lot of experience, thoughts, research, and maybe maturity, I found some tips that changed my attitude towards my colleagues and especially towards the code I work with.

Ask Questions

Reviews and technical arguments always bring a subtle threatening feeling with them, but we can use some ways to try to minimize that.

The first and most important piece of advice I feel everyone should follow is this: for every comment that you leave on a review or every time you think you may have a different opinion on a particular subject, always convey your doubts as a question.

For example, let’s say you’d like to point out a performance improvement. We can formulate our comment in two ways:

  • as a question

  • as a command

Command

Question

What would you say would have a better impact on your pull request?

Let’s see another example:

Command

Question

What’s different between the two approaches?

  • Using the command style, the reviewer assumes he already knows what the author has tried to do or not to do. He/She doesn’t offer a better way to do things nor offers a solution based on what they know. Does this remind you of anyone? I guess it does…

  • Using the question style, the reviewer asks for clarifications, doesn’t assume they know everything about the code and offers a solution without dismissing alternative arguments

It’s not about being “nice”

The tips above will likely make you think I am advocating for lying or playing nice with your colleagues. No, I am not. I am recommending you to give your colleague the benefit of the doubt, and give him a chance to express his point of view on his code.

In general, I’d suggest that you assume that:

  • your colleague has the best of the intentions

  • you have no context, but only a small diff to work with

  • you may even not know something and could learn from it

It’s not you, it’s us

Never ever mention the word “you”. Instead, reinforce the notion of the code as being written and owned by the team, and not by the individuals.

  • Using “you” makes it more likely for the author to take comments personally

  • Use “us” or “we”. Everything should be the team’s responsibility and not the individual’s

Review your attitude

The biggest issue that I have noticed while working with hundreds of programmers is their attitude, as it was mine. Sometimes work is all they care for, and sometimes their approach to the job makes them think that the job itself defines them.

  • They’re angry at the coworkers for not being as good as they are

  • They don’t give compliments, for fear they’d be diminished by doing so

  • They’re sure they are always right

As a result, everything becomes a competition and a race, which is a recipe for a toxic workplace. If you can relate, review your attitude.

  • **Acknowledge others **Not saying you should compliment people on a daily basis, but remember to praise them when you think they did good work, or for example when you notice an improvement in their skills. People love compliments, and they’re free.

  • Is the code you write yours? Probably not. Don’t get attached to your code, and try and remove the feeling from your head that it is **yours **(unless you’re also the owner of the company, of course)

  • Sometimes win, sometimes lose Stop wanting to seem and be right all the time. Coders love being the correct ones and will argue to prove they are for hours. Leaving a discussion without seeming right is, sometimes, the best thing to do

  • **You are not the code you write **Your code is not who you are, nor does it represent your intelligence nor your value as a human being. Sometime your colleague’s comments will be harsh. Sometime they will be right, and sometimes they will be wrong, but don’t let that affect you on a personal level

Stop wanting to seem and be right all the time

Solve conflicts as a Team

If you are in conflict with a coworker, the obvious strategy is to talk it out and solve it between the two of you. Now, we all know that this is often not the case and both of you are absolutely sure that your way is the way.

Of course, sometimes the tip above about trying to not always be right doesn’t apply in this case: you really are sure about your opinion. The thing is, this is not a problem for only the two of you, but for the whole team. This is the sort of situation when the whole team should be involved in the decision, democratically.

  • make your team aware of the conflict

  • talk it out, take a decision everyone is comfortable with

  • make the solution a standard going forward

Make it easy to review your code

Now, let’s see how communication could be handled better by the author’s point of view. Here is a list of tips for helping reviewers, especially the grumpy ones:

  • Small is better Keep pull requests as small as possible and push often. I don’t like to give exact or absolute numbers, as it’s a tough one. If you’re writing code such as HTML, the size of the diff will be much bigger than Javascript or CSS code. Just keep it a reasonable size.

  • It’s best to review early than later Let reviews come from the beginning! If a reviewer will leave 30 comments in one go, it’s going to be a lot more difficult and discouraging to discuss changes and fix them. If you let reviewers review smaller pieces of code, you may be sure that it’s going to be a lot simpler to solve these issues.

  • **Documentation **Provide documentation ****and comment on your own PRs to explain parts that might seem quirky so that you anticipate what the reviewer may comment on. Add TODOs, and delegate larger chunks of refactoring to different tickets, so that the reviewers are better aware of certain limitations and your overall thoughts.

  • **Ask for Help **If you are in doubt, ask for help or for opinions before you submit a pull request. However busy they may be, most folks do love helping

  • **Review your own code **Read and review your diffs before you commit and if your company has a conventions document in place, make sure you follow it

Final Words

Most of the difficult programmers I have worked with were not ill-intentioned. They were extremely passionate for their job, and this is likely the number one reason why we often fall into conflicts while doing what we love.

It’s undeniable that the tech-scene suffers from toxicity and many people contribute to it in different ways. Tweets, public forums, GitHub reviews, etc. I see this daily. But programmers are not inherently bad human beings, for the most part. We are a quite particular class of the workforce: we just really care.

Of course, this set of tips will not prevent a team from having conflicting views: conflicts are part of the job and will always exist, but with effective communication, we all have the possibility to reduce them to a minimum, or better, to handle them better and work in an efficient, peaceful and healthy place.

Ultimately, being compassionate helps teams perform better, learn better together, deliver great products and generally helps enjoy a better day to day work experience.