Today we finish our series on performing an efficient code review. In previous installments, we outlined best practices for the code audit and shared our code review checklist to help you improve the inspection process. In closing, we provide a few more practical code quality assurance techniques and address common questions that may arise during peer code review.
Detecting issues in the code
A code reviewer can find known issues while performing the acceptance criteria check and regular code review (see our code review checklist). To uncover hidden code issues, imagine in detail another implementation of the task and compare it to the original solution. If you consider the alternative more effective, discuss its qualitative advantages with the code author. If the implementations differ drastically, team up with the code author to compare and determine which one to keep.
Avoid multiple review iterations
These recommendations may help to avoid multiple review iterations:
- The code author should self-review their implementation first to inspect for errors, typos, architectural or extendability issues.
- The code author and reviewer should use automated, IDE-integrable tools (e.g., code standard checks, checks for code smell, test code coverage). Use a simple CLI tool and add a button in the IDE to run your own checks.
- If the code author is aware of a specific issue that has not been described yet, it should be fixed in advance or commented on to inform the reviewer of the issue.
- The reviewer should describe the issue in maximum detail so the code author can fix it. The description should provide links to documentation, samples of code from the successfully implemented solutions, or solution patches.
- After the first review, the author should fix described and related issues so they are excluded from the second review iteration. For example, if a code style issue is mentioned once the author should review the entire code for the found issue.
Decreasing the number of issues found during code review
Each code author should maintain a personal checklist of issues discovered in code reviews. The code author should inspect their code against their checklist before submitting the code for a review. This will help decrease the number of issues found during the code review and improve the overall code quality.
How to review different types of tickets
When reviewing a sub-task, verify that the given part of the functionality is implemented properly and complies with the existing one. Check if the implementation has been properly tested.
During the review of a story, focus on its acceptance criteria, technical requirements, and interdependent subtasks. If the story includes refactoring, make sure there are no BC breaks. Also, check if Behat scenarios cover the acceptance criteria.
When reviewing a technical task or an improvement, it’s important to check the related functionality. Conduct regression or smoke testing at this point.
When reviewing a bug, verify that the steps to reproduce result in the expected behavior and that the fix applies to the source of the issue, not the symptoms. To avoid this bug in the future, ensure proper test coverage.
Below are the most common questions asked about code review.
I can’t stand code reviews! How can I handle them?
Code reviews can be less inspiring than other tasks. But, once you find the root of your dislike, you can work it out. For example, if you find the review process slow, time-consuming, or tedious, discuss steps to improve it with your team. Code review has a flexible workflow that can be customized if necessary. If you don’t like the idea of code review in general, try pair programming or other relevant agile/XP practices.
I don’t know this code! How can I review it?
Learn about the code you’re going to review in advance using related services or bundles. This will help you not only check the issue but also better understand the application. Begin by reading the documentation and see how the functionality actually works (on the code level, sometimes even with a debugger). Next, check the suggested implementation. At this point, you should understand how the code functions.
What should I do when there’s an issue in the related code?
If the detected issue is easy and quick to fix, just fix it along with the original implementation. You can add the respective comment to JIRA. However, if the issue is complicated or the fix is time-consuming, you can opt to create a Bug or Improvement in JIRA and link it to the original task. If the issue is a development blocker, fix it or ask for assistance.
What if the code author and reviewer can’t agree on a solution?
If so, they should discuss the solutions and identify the approach that ensures a better quality implementation. A quality implementation is properly built (as per the GRASP principle), simple (KISS), extendable (SOLID), and small (YAGNI). Our extensive code review checklist covers all these principles. You can also use other quality implementation criteria.
What if the code can’t get verified against a code review point or section?
If it’s impossible to verify the code against a specific point of the code review checklist, mark this point as completed as it falls out of the review scope. If it’s impossible to verify the code against a checklist section, consider removing it from the PR description.
Are there any useful tips we’ve missed or questions you believe we should add to the code review FAQ? Share your suggestions in the comments below!