How to Run an Effective Code Review? Practical Tips from a Developer… for Developers

Some may ask: what is the point in doing code review if we have automated tests? Let me ask differently…what exactly do tests test? Is the app correct? Or whether the app has errors? My answer is: tests can only help us know if the app has errors. Tests alone, don’t care about the quality of the code.

That’s why you need a code review. It’s code review that strengthens the trust in the code, ensures the cleanliness of the code. Based on my experience, I have collected a few tips on how to effectively run a code review.

Why do software developers need a code review?

Code review, as I mentioned, builds trust in the code. It increases the sense of responsibility among team members. Thanks to the code review, the whole team feels that the code is a shared property that needs to be looked after.

“However, the biggest advantage of a code review is sharing knowledge. Junior learns from senior, gains experience and senior on the other hand, gains sometimes needed, humbleness”.

In the case when someone new enters the project, quickly implements the project by making a code review. What are the other advantages? Code review is above all is a better code, ensuring code cleanliness, security, optimization. Code review also allows you to see logic errors within the code or failures to meet business requirements, which are usually detected only after the system is implemented without a review.

6 stages of code review

I summarized and divided the code review into several stages:

stage 1 – context building

In order for us to achieve this, we must understand the purpose of the changes and confront the task that was to be carried out. Here the most important thing is to understand why we are providing the change.

stage 2 – understanding what doesn’t come within the scope of changes

stage 3 – understanding of all high-level decisions

This means that I don’t only focus on a particular line of code, but I look at it more broadly. You need to understand how these lines of code affect the entire system.

stage 4 – error search

In addition to the obvious bugs (logical or business), we also analyze the solution in terms of boundary cases.

stage 5 – tests checking

Code review also means checking the tests, whether they cover a sufficient number of cases or are well-constructed.

stage 6 – consistent naming

It’s one of the elements of a clean code and clean architecture. Something that is controversial today and is unclear, in a week can be incomprehensible. And in a month no one will know what’s going on.

And now a small hint. Create a template for the code review, which apart from the description of the change’s essence, the context (eg a link to the Jira system) will also contain a list of things to check. Such a checklist is very helpful because the hardest is to notice what is missing. Note: don’t check something that can be checked much better by tools for static code analysis, like Sonar – just use them.

The last code review step: go back and think

Exactly. Go back and think. Think about whether it can be done better, faster, or maybe simply easier. After you have bitten into the suggested changes in the code and checked if they meet the business requirements – look at once again it from a different perspective. However, it is very important not to bury yourself in endless refactors. Because in the end, the most important thing is to bring business value.

How to increase the effectiveness of the code review?

And again I come back to you with some insights that may be helpful. These are tips for the author of the code and his reviewer, which I implement myself in my work.

• Check your commits

Before you give the code to the reviewer, check it yourself. Look at your commits, check if they are sensible. Then you will also see if there’s no unnecessary trashes in the code

• Sharing knowledge

Code review is done by junior and senior. I have already mentioned this before, but it is important. Junior is learning and implementing, and the senior realizes that he/she may not be infallible. Besides, it’s a great opportunity to be a mentor.

• Engage your team

Don’t keep the knowledge for yourself when significant changes in architecture or design are made. Everyone in the team have to know about them.

• Describe your commit well

Don’t write what has changed in the code, because it’s seen to all. Instead, write why you have made the changed? Also apply the rule: one commit – one reason for the change.

• Customize the comment to the recipient

In other words, use different language to a senior or to a junior. This is also a good time to share the knowledge to new people in the project. Oh – and one more thing. Don’t make personal experiments. The commentary is for the changes, not for the author.

• Comment the code in the code. That’s all.
  
  
• Ask engaging questions

And don’t suggest a solution. Try not to use the instructions to do something in a specific way, otherwise, the author of the code won’t learn anything.

• Respond to comments

So it’s known, that the fix is implemented. Treat code review as a conversation.

• Inform about the end of the code review

So that the author knows that he/she can already make all the fixes.

• Don’t go overboard with the amount of change

Don’t go overboard with the number of changes. No one will detect errors when the number of changes is too large. Split large topics into smaller parts. “Divide et impera” as the ancients used to say 🙂

When does the code review may be a failure?

When the code review is done without preparation. It certainly will not work. For the code review to be effective, you must devote yourself to it. Find the right moment – don’t just jump into it.

This task is difficult because you have to go deeper into the context. You need to understand what the author meant. That is why it is important to make some room and cut yourself off from all disturbances.

In addition, it’s best to run a review code with a fresh mind. Some adhere to the principle that the code review should be done only in the morning. Personally, I think it can sometimes be a waste of time, cause the author of the code has to wait for the review until the next day. Therefore, if you’re reviewing a small change, do it the same day. And remember about splitting larger topics.

Summary

That’s it for my experience with code review. I hope that you will find in this text pieces of your daily work. Do you know other ways to do a code review? Please share it with me. I’d like to read it.