PROGRAMMING
The Art of Code Review
Why is code review essential? And what are the best practices?
What is code review?
We all write code, and we would love to commit our code to the main pool of codes. It is an exciting moment, and we cannot wait to see our latest masterpiece in the main repo. Let’s commit and merge. Wait… do I need to ask someone to review my code?
In many companies, especially small companies, it is not a necessary process. But large companies with hundreds of developers and millions of users cannot afford a simple and avoidable mistake. Code review is a good (and sometimes forgotten) practice among developers.
A common excuse for many teams and organizations to skip code reviewing is “We are fast and agile.” Although it seems that code review makes the process slower at the beginning, committing codes with bugs and flawed logic makes the process less efficient after merging. Also, sometimes a tiny mistake (especially on security aspects) can cost companies a huge price. Always remember that there is a tradeoff between velocity and quality. Ignoring code quality or velocity, in either case, leads to an inefficient process. An efficient code review can balance the velocity and quality of development.
The article is written for you as a code reviewer. If someone kindly asked you to do code reviewing, there are some tips in this article that can help you to do it more efficiently.
Why is Code Review crucial?
- A second eye on your code: After hours of coding and running, debugging, and rerunning, catching some unexpected bugs and edge cases could be very difficult for the code authors. It is very common to miss some edge cases just because the author focused on the major cases. Even with the best testing plans, the author still might miss some bugs that normally do not happen. Here is the time that code authors need a second eye on their code.
- Communicating best practices: Code review reminds everyone (including the authors and reviewers) of the best practices on a regular basis. If you are on your own, you might forget some aspects (or even not be aware of) of best practices in your field. The code review process on a regular basis and with different reviewers is like periodic reminders for everyone to follow the best practices. For example, as a solo programmer, you might sometimes ignore a reasonable testing plan, but a good reviewer asks you to do some testing plans.
- Learn while reviewing: Remember, code review is not a supervision task. Sometimes, reviewers learn more during the code review process compared to authors. Sometimes, the code review process is a learning opportunity for reviewers, especially if the author is an experienced developer.
- Get more involved in related projects: It is challenging to sync every team member of the latest features in a product or every aspect of a project in the organization. Code review, especially when it happens between members of different teams, makes the reviewers get familiarized with the latest updates and features of a product or a project. Teams and organizations without a code review process usually have a more challenging time syncing later when many changes have been added to the product.
- Enforcing coding standards across developers: Not all developers are at the same level. But to work as a team, we must maintain a basic level of standards for our shared codes. The minimum standard of the code makes it easier for both experienced and inexperienced developers to work on the same project. The best approach to enforce the minimum code standards is to have a code review process for every single code before merging to the master repo.
What are the best practices for code reviewers?
Now that you are hopefully convinced that code review is necessary to work as a team, I would like to share some tips to make you a better and more professional code reviewer.
- Be respectful and friendly: THIS IS BY FAR THE MOST IMPORTANT TIP. Remember, the reason behind code review is not to humiliate others or showcase your coding skills. The main reason behind code review is to be able to develop codes and products as a team. As with any teamwork, respect is the number one rule for being successful. Try to make concise and clear but respectful comments. Also, remember, do not make unclear comments to just being friendly or respectful. Being clear, concise, and respectful are not in contradiction.
- Be open-minded and accept different approaches: Every person has a coding and thinking style. Different people can write totally different codes to accomplish the same task. As long as the code has met the standards (in terms of performance and style) and it makes sense, you must be open-minded to that approach. We all know you might have a different coding style or approach, but the reviewer is not in the author's position. Try to be open-minded to other approaches and help the author to understand possible flaws through their approach.
- Ask questions, actually too many questions: Don’t be shy to ask questions. It is totally normal not to know about the code and even its basic goals. It might be because you are not familiar with that project or the author has not communicated the code's objectives very well. Also, sometimes authors get too involved in the problem that some aspects of the problems become obvious for them and they forget to explain those aspects to others. It is good to show them what parts of their work are not clear by asking them questions.
- Ask major issues first and minor issues later: It is recommended that the first rounds of review focus on major issues and the overall approach of the code. Many minor issues will be automatically deleted or changed during the revision of major issues. When you feel comfortable with the overall approach (keep point #2 in your mind, though), it is time to comment on minor issues.
- Refer to the styling documents or make one: It is better to show why you are making some code styling comments by referring to the styling document you have in the organization. If you don’t have such a document, create one. With this approach, the author has a better idea about the standard style and can learn it for future collaborations.
- Make it clear if it is not important: If your comment is just a suggestion or not an important comment, mention it explicitly with something like “nit” or “Just a suggestion.” This way, you make it clear to the author that it is up to them to apply these changes. It also helps the author to balance between velocity and quality when the process needs to go fast.
- Leave some good comments: Sometimes, even with the most respectful comments from the reviewers, authors feel bad to read tens of critiques on their code after putting in too much effort. It is a good idea that sometimes, the reviewers leave good comments to appreciate pieces of code that they look it is written well. It can be as short as “Clever idea on this part” or “nice approach to this issue.” After all, it is a good feeling for authors that you appreciated their hard work and noticed some of their efforts.
Summary
Remember, always be respectful and friendly in your code reviewing. Ask questions, make clear comments, and always leave good comments.
