Team communication

Communication has been a hot topic in the software development industry for some time now and its importance is only going to rise as the industry grows.

That being said, it is not easy to communicate well since people within a company may have different personalities and even cultures, making it had to convey information in a way that reaches everyone. What can we do to make it easier and more efficient then?

Good communication at a company level is something that most software developers don’t have to deal in the early stages of their career, so I will focus on the communication inside a team and what helps me in my day-to-day work. I consider that small companies behave like a team most of the time, so the knowledge should still be applicable in these cases.

If the following topics sounds obvious to you, this is a good sign.

Reviewing code

The first thing a team should do is to create a standard when asking for code reviews. It is easy to lose precious time arguing about the best syntax or reviewing code that is still in progress to only discover that most of it changed and your comments are now irrelevant. To solve this it is important that a team:

• Decides beforehand on the expected syntax (avoid bikeshedding)
• Make it clear when the code is ready for review

An example for the last bullet point would be writing in the title of a pull request that this is a work in progress (WIP), and removing the [WIP] from the title when the code is ready. Tagging a pull request as WIP is also helpful with labels.

Writing code

A much bigger problem in the long run is not giving the right amount of context to the rest of the team when writing or changing code.

Sayings like “good code doesn’t require comments” only exacerbates the problem in my opinion, since the code can’t possibly express the context in which it was written and the knowledge is lost as soon as team members leave the team.

One idea to address this issue is to answer questions like “Why is this being done?”, “What are we trying to achieve” and “What could go wrong” when asking for review. These questions will serve as a guideline for the review and will be extremely valuable during a future refactor of the code. Commit messages are a good medium to convey some of this information.

If your team works with pull requests it is valuable to create a standard template. The idea is to explain to reviewers what is going on so they don’t have to go to the trouble of figure it out by themselves and potentially asking question that have already been answered somewhere else.

Making decisions

It is easy to make decisions, the hardest part is remembering why the team decided on them after a few months away from the problem. I have already mentioned the idea of answering questions when writing code, but some things are better done in a “formal way”. Creating documents with a proper explanation of the situation and having an easily accessible place to store them is of utmost importance. In these documents we can detail the situation, add diagrams and so on.

Discussions

If you are discussing something with your coworker and doesn’t seem to reach a consensus over the problem don’t extend the discussion on slack, pull request, email and so on. Nothing beats face-to-face communication. Most of the times the situation will be solved and the stress level will be kept to a minimum. A video call would be the second best option when people are not in the same physical place.

Summary

It’s all about context and setting expectations. By getting those topics right the team will work in an efficient way, avoid useless discussions that over time contribute to burn-out of team members.