Best Practices for Pull Request Management and Code Review
Let's go through the best practices I noted during my experience for both authors and reviewers to create an efficient code review workflow.
Don't rely on the reviewer to find bugs
The reviewer should not be considered as Quality Assurance (QA) to find bugs and errors in the pull request. The author needs to carefully review the code on their own before requesting a review. This doesn't mean the PR should be perfect and error-free.
We're all human, and it's possible for things to slip past us. That's where the reviewer comes in as a second pair of eyes to check for any missing parts. However, solely relying on the reviewer and not checking anything in the code before creating a PR will waste time for both sides. It will result in multiple back-and-forth changes and discussions, ultimately delaying the delivery.
Make sure there are no blockers for a reviewer
If your project has CI/CD workflows or pipelines, ensure that all checks pass before requesting a review. Sometimes authors are overly confident that checks will pass and request a review immediately, without waiting for the status. However, when reviewers open the pull request, they discover failed checks and need to communicate with the author to fix them.
This not only applies to CI/CD, but also to situations where there are merge conflicts or outdated commits in the pull request, making it difficult to review and considered as uncompleted work.
Provide a clear and detailed description
The reviewer needs to understand the goal of the pull request. Poor descriptions make it difficult to understand the business logic behind the code, and this negatively impacts the review process.
The best way to provide a detailed description is to use templates and helper indicators to provide more context for the reviewer. For instance, defining the goal of the PR, specifying its desired outcome, including technical notes and labels to indicate whether the PR is ready for review or still in progress, and so on.
Check out BattlePlan ticket templates for examples.
Be considerate when providing feedback in review comments
When reviewing code, it is important to consider the author's feelings and avoid offending them with your comments. If the reviewer has suggestions for improvement, it is best to phrase them in a non-confrontational manner. Instead of directly instructing the author to make changes, it is recommended to start sentences with phrases like "I would suggest to...", or "It could be more efficient to..." and continue explaining the reason behind the suggested changes.
No one is perfect, and demonstrating superiority on a pull request is the worst toxic behavior a reviewer can exhibit. If you find yourself in such situations, it is best to directly inform the reviewer that their communication style is unprofessional.
Sanity checks might not be enough
If it is a large pull request that potentially introduces breaking changes, relying solely on sanity checks might not be sufficient. This is because the actual logic needs to be tested locally to ensure that it aligns with the provided requirements.
It seems that you understand all the steps and the code appears to be fine. However, there may be underlying issues that are not visible until the entire application is run locally and thoroughly debugged.
Dealing with a procrastinating reviewer
If you have created a pull request and your reviewer is procrastinating on it, here is the best way to handle the situation.
This is a joke. Do not try at work.
Conclusion
By following these practices, authors and reviewers can work together effectively and deliver high-quality code. Remember, the goal of code review is to improve the code and collaborate as a team not compete over who writes better code or flex on each other.