Code review and team communication How not to suck as a teammate

Before there was code, there were people. And after, too. So I will start this post by telling you: you work with people. “Oh, I became a developer so I would work with code only. I don’t deal with people very well.” Sorry, but that won’t happen… You ultimately work with people. And, by working with people, you have to follow a few rules to be a good teammate, right?

Soft skills are fundamental to evolve as a professional developer and communication will play an important role in the development and quality of the projects you might work in. So let’s take some time to talk about why and how to communicate professionally and thoughtfully in your daily work routine.

Code review

What is it and why do it?

As a team member, you will be required to review your colleagues’ codes — you will be performing a code review.

A code review is a peer assessment to guarantee code quality and fix bugs. With this, the goal is to make the code more maintainable and readable, as well as guarantee it adheres to the project’s standards. Let’s talk more about this.

A code review is a two-way process, in which both parties will learn more about the code and may work together to achieve a better version of it, when necessary, by finding solutions to problems and guaranteeing the code follows the project’s patterns.

Dos and don’ts

As with everything else in life, there is a better way to do a code review — and it isn’t always strictly the same.

First, let’s talk about the points that are always the same.

As a reviewer

How you communicate

First of all: be nice! That’s not rocket science. The code must be reviewed and you will be severe towards it, but that doesn’t mean you need to be rude to your teammate. Remember that written communication is easily open to interpretation, so be clear and polite without ordering your peer, only offering suggestions. Remember you are not reviewing according to your particular taste, but to the overall patterns followed by the project and check if the message is coming through. Otherwise, try to schedule a moment with your colleague so you can exchange knowledge. And, most importantly, accept that, by reviewing someone else’s code, you must be open to learning from it.

Basically, don’t be a jerk!

Understand what is expected

Before you even start to write your review, you should understand what is expected of the code — know the context. How to be sure of it, though? There will be a ticket describing the problem, or maybe a GitHub issue… it should be indicated to you somehow where to find more information about what this code solves. If it isn’t or the information is confusing or incomplete, you should talk directly with your colleague responsible for the code so you can understand it better and review it according to what is expected.

Understand how the code works

Before any suggestions, stop and think: how is this code supposed to work? Don’t make assumptions without enough information. If possible, execute the code and see it for yourself. However, there is a fine line here that might be crossed — maybe the code is confusing and needs a refactor so that in the future the team will not face unnecessarily complex code.

Make educated comments

So you understand what is expected and how the code works, but still, you have some questions? That’s what the comments are for – use them to get proper answers. Again, don’t be rude! Communicate showing your true questions without unnecessary confrontation. The idea is to make sure the review is efficient and produces the proper results — a good code — and not to criticize the author in any way.

That being said, don’t suggest something if you can’t back it up. Think first: “Is there any reference I can add to sustain my argument here?”, and, if there isn’t, it might be because it is only your preference and not exactly something that might improve the code. Always comment with all the information, and add the sources you used and the links, if there are any. This will make communication more efficient, without the back-and-forward of information.

As the author of the code

If you wrote the code and opened a pull request, you should know you also have some communicating to do. Give all the necessary information beforehand: what are you implementing and why? This right here will help you write a great pull request.

After getting your PR ready, remember: this is not your code. This is the team’s code, written by many different people throughout the project’s years of life. That being said, any critics of the code are not personal, so assume your reviewer has their best intentions in mind when they criticize the code. If it’s getting confusing, request a call and take a minute to explain or ask questions.

Team communication

Other than communicating through code review, you will have to interact with other human beings daily (even if you work from home). Let’s not take team communication for granted just because your teammates are on the other side of this screen you are using right now. Communicating efficiently means simply doing your work correctly, nothing more.

In your work’s daily routine, you will have meetings, schedules, reports, and other common practices. Don’t take them for granted. Participate in those practices accordingly.

Communicate your problems

You might find yourself in situations you did not expect. Let’s explore this scenario and imagine you are implementing a feature you estimated would take three days to finish. But on the first day, you had a problem with your computer and suddenly you could not work. Instead of communicating, you decided to fix the problem and follow along on the task. However, you lost precious time and could not complete it on schedule. Or worst, you could not fix the problem, the three days went by and you neither communicated your problem nor delivered the new feature.

This is an example of poor communication where you not only affect how your team perceives you but also compromise the efficiency of the overall work — someone could be waiting for your feature to be implemented to move along with their work, for example.

So, communicate your problems! Be aware that working from home does not mean working alone. Ask for help. Someone might have been in your shoes before and could give you a solution to your situation.

Choose how to communicate

How formal should you be while communicating? Well, it depends on the situation. You must learn to read the room, so to speak.

Sometimes you might choose to speak in an informal manner, where the development of the situation will be faster and you will reach a quick result to your issues. However, important and serious situations could be lost in this channel of communication and you would have to face the repercussions in the future. In these cases, a more formal manner should be chosen. Even though it will take longer to finalize your issue, the result will be more reliable.

If you’re asking for help with a simple issue, you could go informally and discuss the situation quickly with your teammate to reach an agreeable result. However, if you need to make a major change in a long-term feature that will have a side effect throughout the project’s code, you should be formal, discuss with proper arguments to do so, and wait to hear the answer before assuming you should proceed.

Don’t leave it implied

You were finishing up something and came across a bug. It’s small and you decide it won’t be such a big deal, so you leave it there and don’t communicate with anyone about it. A small bug can escalate and become a big deal at some point, and the whole team will have to work towards fixing it instead of focusing on their work. Always communicate problems when they are small and easily fixable or else they might become a snowball and hit you with full force.

Be efficient with code and communication

After all of that, I guess we can conclude that to be a good teammate we must pass along important information, be able to hear all colleagues without letting our ego win, and be mindful of others all the time. We can be efficient with code and communication at the same time, so let’s practice what we talked about today?

References

Previously in the TMGCC: Fundamentals of HTTP and Web Development

This post is part of our ‘The Miners’ Guide to Code Crafting’ series, designed to help aspiring developers learn and grow. Stay tuned for more!

We want to work with you. Check out our "What We Do" section!

Code review and team communication

How not to suck as a teammate