How to ease your code review
At GOGOVAN, we understand how code review is crucial for delivering quality products: early detection of defects, consistent coding convention, code knowledge sharing with our peers.
This article is about how we prepare the pull request to get the best out of the code review from our peers.
Pull request description:
This is the first thing code reviewers will see when they pick up a pull request. Also, any developer should be able to pick it up anytime. That is why everyone should make it clear, descriptive and accurate.
For that, it takes no special skill. Just structure your pull request with the following questions:
- What does this change?
- Why is this change important?
- How do we test this change?
We have developed a standard pull request templates to keep the structure consistent https://help.github.com/en/github/building-a-strong-community/about-issue-and-pull-request-templates#pull-request-templates
To bring more clarity, add screenshots or links pointing to the design document to help your reviewer.
Give clear instructions to your reviewer so they can test what was agreed during the sprint planning.
Finally, code reviewer will complete a checklist to validate all the tests.
Pull request size:
KISS — Keep It Short and Simple.
Sadly we have all been through this. Or at least we have witnessed it.
Small pull requests are easier to review and more engaging for discussion.
Small pull requests can be released faster and make the delivery process more efficient.
However, if the pull request turns out to be bigger than expected, we break it into smaller pieces and treat them as separate pull requests. This can avoid fogging our code reviewers’ minds and miss out on things.
Commit size, commit sequence, and commit message:
Same as pull request. A commit should be small.
Each commit should cover one intention and the commit message describes concisely that intention.
The commit sequence can be seen as a guide that would walk the code reviewer through the implementation step by step.
We commit amend / fixup / squash to often keep the sequence logical and easy to follow.
When we address feedbacks from code reviewer, we add a new commit on top of the reviewed commits to isolate the change. The commit message describes the feedback that has been addressed.
Pull request comment:
Sometimes we may foresee an implementation detail would be subject to discussion. A variable naming for example. We will leave a comment to explain the reason why to help reviewers to understand better.
Final check before requesting a code review:
Like any chefs — Taste the food before serving. We as developers do the code review ourselves first. Confirm that the unit tests and end-to-end tests are successful before rolling it out to reviewers.
I hope you enjoy the read. Feel free to drop any feedback in the comment section and exchange ideas!
