A Simple Guide to Make Better Code Reviews
By: Luis Guerrero
Tags: Software Architecture, Programming, Software Engineering, Software Development, Code

Photo by Markus Winkler on Unsplash

Code reviews are an excellent tool for maintaining good quality in the codebase but only if done right. Although there is no magic formula to do a code review, in this article we will discuss some good practices you can consider while performing it to get the desired result.

What to look for in a Code Review?

Photo by Markus Winkler on Unsplash

Consistency

You should always have a style guide for your codebase, this guide can include things like naming conventions, imports order, etc. and these rules should be followed strictly unless the document says otherwise, a lot of these rules can be enforced by using automated tools like linters, formatters, and hooks but some others don’t, here is where the reviewer should pay the most attention.

Functionality

Does the feature or the fix work as intended? What about edge cases? You should always try to run the code and check that it works correctly, especially if involves UI changes, always try to think like an end-user and what actions could them do that could potentially break the feature.

Complexity

So often developers make the code more generic than it needs to be or add functionality that isn’t needed because they think it could be used in the future, this type of over-engineering can lead to some problems, being the most common:

Spending more time to write code and tests that could or not be needed, or having to refactor code because the requirements weren’t as thought.

Have unused code in the codebase which may lead to slower times of deployment or bad performance.

As a reviewer, you need to check that the code meets this requirement because even if there is a high chance this will be needed in the future, it could happen that when the time arrives isn’t needed or that the requirements are different from what was thought originally.

Testing

All of the new code should have unit tests attached either by adding new ones or updating the existent ones, as a reviewer you should at least check that the main cases are tested because as you may know already this would allow refactoring easily without breaking things.

How to leave comments in a Code Review

Photo by Volodymyr Hryshchenko on Unsplash

Write why not what

Often by leaving just comments about what you want to be changed can be seen as a mandate, more when you review code from junior developers, this makes them do the changes asked without thinking about the reasons which lead them to do the same mistakes over and over again

For example, when leaving a comment or a change request that is linked to a style rule, you can link the place where is written so the developer knows why that should be implemented that way.

Recognize the good work

Code reviews shouldn’t be only to detect mistakes, it is also a good place for appreciation if the developer did something good, let them know, this will increase their confidence and very likely will lead to better code quality.

Be clear

Be clear on the outcome you expect from your comment, are you requesting a change, asking a question, or just being informative? This way the developer can act accordingly, nobody is a mind reader.

Don’t comment just because

Sometimes (more often senior developers) want to show their knowledge by having something to say, it is not mandatory you find mistakes when doing a code review, there will be times where you only need to approve them as they are, there is nothing wrong with it, nobody will think you didn’t review it and if someone else finds something you didn’t, don’t worry, we are humans and we make mistakes.

Guide, not solve

It is the developer responsibility to make the changes to improve the code, sometimes it seems easier to leave a comment with the code we as reviewers would like to see implemented, but this is not helping anyone, you’re working on something is not assigned to you, and the developer is not learning, if you want this to be useful you could do a pair programming session where you explain and the developer understands what you are proposing.

How to solve conflicts in a code review

Photo by John Schnobrich on Unsplash

Facts not opinions

When a conflict arises in a code review technical facts should prevail, if the code is maintainable, readable, well performant, and solves the problem, there shouldn’t be motives to request changes if we don’t have evidence of the contrary.

Pair review

Often it is difficult to express our emotions or to describe accurately what we are thinking using text comments, if something is very complex to be addressed this way a face to face communication can help to understand better what both, reviewer and developer are thinking and get to a consensus.

Lean on a technical lead

If there is no consensus on some decision you can ask a technical lead to help solve the situation, this doesn’t mean the reviewer and developer should do as the technical lead says unless it is affecting the times of the project, but mostly to have another person to look at it and give their advice.

Conclusion

As I said in the beginning, code reviews can help to improve the code quality and learning but they need to be done correctly, otherwise, they can become a burden that won’t help anyone. I hope this article helps you and your team to use this excellent tool to make your life as developers easier.