To Code Is To Communicate: 8 Ways to Write Better Code Reviews

When I started programming, Code Review wasn’t part of my routine. First, like everyone, I learned how to print 

Hello World

 in the programming language that was studying. Then, what is an 

if

, 

while

, 

for

, and other essential structures. Sometime later, I was coding.

More topics came out, and I learned a bunch of complicated stuff. Soon, I realized that not everything I’ve been learning all this time was a good practice. For instance, how to access that global variable, which ends up in many messy codes, and introducing big problems in the application.

Programming is a discipline in which you get better as long you practice. There are tons of concepts and ideas. An excellent way to accelerate your learning is through Code Review. Even when working alone, you can learn by reviewing your own code.

Here are some bullets to improve your communications skills on Code Review:

1. To code is to communicate

Experienced developers write code that communicates its intention. When I started writing my first lines of code, I would write it not caring about indentation, best practices, or complexity. So, my team and I would meet these same pieces of code in the future and get mad.

If you read the code that you wrote and found it hard to understand, maybe you would think: “I’m just out of context, this was making sense in the past.”

Or maybe your code does not communicate your ideas well.

To communicate isn’t just getting rid of syntax errors and making code work. The code should communicate ideas to people through a programming language that computers can also understand.

You should adopt semantic variables, classes, modules, and methods names. For instance, in Ruby, we avoid using particular prefixes such as 

is_paid

, 

get_name

 and 

set_name

. In their places, we use directly 

paid?

, 

name

, and 

name=

.

My advice is to use idiomatic and features that the programming language you use offers to you whenever possible, and figure out ways to better pass the message.

Why wouldn’t we be worried about semantics, typos, and styles? We should care for the quality of our code, and the many concepts that define it. You can start by using a linter to collect some issues from your codebase automatically.

2. It’s about feedback

You’re coding and pushing changes to codebase and wonder: How can I receive feedback for these codes that I’m writing? The answer is Code Review.

You should ask your peers to review your code, create branches, and open Pull/Merge Requests instead of pushing changes straight to the 

master

 branch.

It gives visibility to the entire team what is delivered, help each other on improving code quality and propagate knowledge between developers.

3. Everyone makes mistakes

We need to make ourselves vulnerable when opening a Pull/Merge Request. When people comment, we need to be open-minded and receptive. It’s a vulnerable position, I know, but that’s the best position to be when receiving feedback.

Developers make mistakes. They miss requirements, make typos, or introduce bugs. Be you an entry-level developer or a senior engineer mistakes happen. So don’t be afraid of commenting or asking questions in a Pull Request that the author is an experienced developer. Pull Request is a great place to learn more about the codebase and other perspectives.

The more people review the code, the more thorough the reviews are, and the clearer is the communication. Too many merge approvals without interaction could also be a potential problem, try to engage your team to interact in many ways: asking questions, suggestions, appraisals, discuss style, and so on.

4. You’re not your code

When you’re receiving feedback, you can read a comment that you’re not expecting. It may bother you, but don’t take it personally. Nobody is doing it to make you feel bad or let you uncomfortable among other developers

Always be humble. Learn from your mistakes and try to create notes of your common errors if you realize that you’re committing it more than once or twice

5. Keep a Power and Ego down

When commenting on a Pull Request, you can offend another person’s feelings indirectly. What you write has power. Find the best sentences in your review comments to encourage discussion. Explain why you’re suggesting a change, or even why that implementation doesn’t work. It avoids falling in common mistakes that feed your ego.

Appealing for constructive communication and talking about failures will promote an open and continuous improvement culture, which is excellent for everyone. Remember that you can always use an Automated Code Review tool as SourceLevel to help you comment on styles and other stuff, keeping the discussion running for most-important details.

6. When to use power: 

Request Changes

In GitHub, you have the option to 

Request Changes

 when submitting your Review. I’ve seen a lot of developers misusing this option, and if you don’t understand the consequences of using 

Request changes

, I would recommend to just select 

Comment

.

Example of bad practice for Request Changes

When you choose to 

Request Changes

, you prevent the Pull Request from being merged: do you agree with me that this a power that you have? To block someone’s job, you must have a real good reason for doing that. In most cases, if you comment, the author will accord or at least reply to your comment before merging.

So if you need to block any PR, I recommend doing that only when you got a Continuous Deployment mechanism that will automatically deliver this code to production and would break functionality there. In other cases, you can use several ways to communicate with your peers and make sure the author will comment consider your comment. If the author discards it, you and your team may have a significant cultural problem to solve.

7. No offensive communication

So you want to improve communication in your reviews?

• Stop commenting only offensive emoticons, such as 🤢, 🤮, 😵, 😱, 💩, 🙈
• Start explaining why this is bad and how it can be harmful to the codebase
• Stop commenting single ✂ or 🔫
• Start also making explicit what to remove from the code besides using emoticons
• Stop asking to refactor without examples
• Start using 

  Suggestions

   to allow the author to visualize what are you purposing
• Stop ignoring refactors and enhancements
• Start by giving congratulations/appraisals to the author by doing that
• Stop commenting in Pull Requests and don’t check if the author or other peer interacted with your comment
• Start using 

  Notifications

   page or configuring your email to receive when someone replies to you

That’s not all. You can also search for trending repositories and check which practices other developers use to communicate during Code Review in the Open Source community.

8. Build with your team

All these practices can be introduced and practiced day-by-day. There is no need to rush: talk with your peers and consider building a guidelines repository. Put in it style guides, linter configurations, and documents describing which practices everyone should follow.

SourceLevel automates code reviews. It reads rules from files in the code’s repository. Don’t worry if you or your team don’t have one. It fallbacks to linters’ configs we maintain to guide you on the journey of becoming a better developer. Preferably, together with your team.

I hope you enjoyed the content. Thanks for reading.