Code review is one of the most important endeavors of software engineering. As a software engineer when you write code, the end goal is to take your written and working code to production where customers can get value out of it. However, your written code has to go through multiple checks like gated tests, code reviews from other software engineers and release workflows before any customer can leverage any value from it.
Code reviews are an important exercise in the software development life cycle. Code reviews are generally facilitated via a pull request which is a webpage where other developers can go and see the intended set of lines that one is trying to change in a given codebase (link to an actual pull request). Getting code reviewed by other software engineers who know about the code base benefits in the following ways:-
Helps catch corner scenarios that one may have missed
Helps surface any performance bottlenecks that may be introduced by new code
Exposes opportunities for refactoring if new code has duplicate code
Helps in generating ideas on future work streams for the software product.
As you can see, code review is a collaborative activity that involves participation by code submitters and fellow developers. Since this activity involves requesting other folks on the team to invest their share of work time, it needs to be coordinated and managed well. In this article, we will read about a few code review-related best practices for code submitters that will help the code submitters leverage the knowledge of fellow software engineers and also help them cordially coordinate this activity.
Provide a detailed description for your pull requests
We must be able to describe the code that we have written in detail to let other developers know what is that we are trying to achieve with the pull request. A detailed description goes a long way in enhancing a reviewer's understanding of the scope of change that one is trying to achieve via the pull request. The article "Writing A Great Pull Request Description" gives some nice guidelines on what to include in a pull request description. Some of the information that you could as a part of the pull request description is as follows:-
Summarize what the issue you are trying to fix or what new functionality you trying to add
How does the pull request help to fix the issue or what is the overall scope of the changes in the pull request
Provide details on what testing was done, if automated tests were added as a part of the pull request or provide a screenshot of the manual testing that was performed.
Divide your work into small pull requests
It is advisable to divide pull requests having a larger scope of changes into pull requests having smaller scope changes. According to the article, the ideal size of a pull request shouldn't be more than 250 lines of code change. Larger pull requests (more lines of code change) take more time to review and potentially could introduce more bugs into the system. So it may be helpful to break down your big pull request into smaller pull requests which allows you to push your changes incrementally into the code base without degrading the overall quality of the code base.
Provide adequate review time
We all know that most software developers are fairly occupied with their assigned tasks and meetings. Different software engineers review pull requests at different times of the day based on their schedules. So unless you need to commit a fix to an urgent customer-found defect or your service is facing downtime, give your fellow engineers enough time to review your pull request. It is reasonable to provide one or two business days to your fellow developers to review the code and provide feedback. If the turnaround time is longer than expected then you may send reminders asking your fellow engineers to prioritize code review for your pull request.
Do not ask for reviews on incomplete work
It is important to realize that code review activity takes a significant amount of time from your fellow developers. Asking your fellow developers to review a pull request that will have more changes from you in the future tends to waste the time of your fellow developers. Hence, it is advisable to ask for a pull request to be reviewed only when you think you have finished the code for all the modules/files that you intend to get reviewed for that pull request.
Close amicably on the review comments
There will be many times when you may not agree with some of the code review comments provided by your fellow engineers. This disagreement may be because of many reasons like mentioned below:-
Lack of clarity in understanding the scope of the pull request
Request for some code change outside of the scope of the pull request
Feedback on code style
General feedback on the naming convention for variables or function names
You can choose to respond to the code review comments that you think add little value to your code change however you want. This code was conceptualized, written and tested by you after all. However, closing the code review comments without proper discussion indicates that you are not respectful of the time spent by another engineer reviewing your code. This could lead to future problems like other developers losing interest in reviewing your pull requests or approving your pull request without taking a closer look. In either scenario, the quality of the work you deliver as a software engineer in terms of pull requests would go down over time and you would end up introducing more bugs in your codebase. This can also downgrade the code review culture in your team if multiple engineers exhibit this sort of behavior.
To amicably close on the review comments received from a code reviewer that you happen to disagree upon, one could either respond to the code review comments and wait for the reviewer to close on the code review comments themselves. This way all the conversation is recorded in the pull request and could be referred to in the future if need be. Another way to amicably resolve disagreeable code review comments is to schedule a one-on-one meeting with the concerned reviewer and resolve the review comments.