Article summary
I want to share a trick that practically eliminates Pull Request feedback! All you need to do is ensure that your code is of extremely high quality, follows best practices, and is clear and concise. If you can manage that, you’ll barely hear a peep from your reviewers!
I’m kidding of course, that’s no trick. These are just things that we all strive for when writing code. Actually producing code that lives up to that standard is easier said than done. That said, I do have a strategy to share that can help reduce the number of PR comments you receive. The less clickbaity title for this post would read: Improve Your Code Quality through Iterative Self-Review.
Power of Self-Review
All of the best developers I know preach the importance of self-reviewing your PR before requesting a review from another developer. I must agree, it’s an excellent practice to follow for developers of any experience level. Self-reviewing provides a filter to catch small mistakes like typos or lingering log statements. It also offers an additional holistic view of your work where you can confirm that you’ve nailed the architectural decisions. Identifying and addressing any issues that you observe will surely reduce the number of comments you receive once you publish your PR.
Through this practice, I’ve noticed that I am able make quality contributions more quickly. I don’t often need to wait for someone to tell me that I’ve made a silly mistake, or that an implementation was missing the mark. Keeping in mind that it’s likely that nobody will be more familiar with these changes than me, I can take the opportunity to get it right.
Iterating
Eventually, I began to realize that I was getting a lot of value out of one of the side-effects of the self-review practice. Every time I checked off a file through the PR review UI, I both gained confidence in my changes and also closed a tab. I could let go of a piece of the context I was holding, effectively telling myself, “This file is all set.”
I found this so helpful I began reviewing my changes earlier and earlier in the development process. Nowadays, I conduct a review once the core changes are “roughed in” or I feel like I’ve lost the thread of what I’m aiming for. I’ve found this an extremely effective way to identify any incomplete or unsatisfactory work. I can then give my attention to those areas to bring them up to the level of quality I expect. This helps me regain my focus and allows me to continue moving forward.
This approach really pays dividends when performed iteratively. Ultimately, it becomes a simple exercise of using the PR review UI as a todo list, except instead of a list of tasks, it’s tracking files. Most PR review UIs offer the ability to indicate that a file has been viewed, usually denoted by a checkmark. In this approach, a file earns a checkmark when its changes are “good”.
Iterative Self-Review in Practice
When I’m ready, usually when I’ve mostly completed the work or potentially need direction, I create a PR. Here’s my workflow.
A First Pass
In the UI, I look for files with the smallest or most inconsequential diffs, things like renamed imports, generated files, or one-line changes. Those files earn a checkmark right away. Next, I look for minor changes, things I can quickly and confidently determine would be “okay” if merged. My goal here is to check off as many files as I can. I do try to be uncompromising though, if I see something really should be fixed, I avoid checking it off until I have a chance to resolve it.
Once I’ve checked off what I can, I determine where to place my focus next. Sometimes I’ll have left a piece of code partially done, maybe intentionally imperfect, to avoid wasted time — this can be a good place to go next. In other situations I’ll have a bigger architectural issue or implementation to fix. Picking the next thing to do is more of an art than a science. Sometimes I just go for the thing that is most interesting at the moment.
Refining
Without fail, my changes will touch at least one file I thought was “good”. Nothing wrong with that. I expect to modify logic, refine tests or restructure code as I iterate. Thankfully, the UI is tracking the changes to these files and will automatically uncheck anything that gets modified when it’s pushed.
Once I’ve finished addressing a problematic area of the code, I return to the UI. I take the same approach as above; looking to check off any minor changes and revisit the files I may have inadvertently caused to be reverted to unchecked. It may take a few iterations but eventually, the small changes will be checked off.
Switching Gears
Next, I’ll switch gears and focus on the major changes; things like entirely new files, reorganizations, etc. I typically give these changes a bit more attention but still less than I’d give a typical code review. If I notice something to adjust, I’ll make the changes necessary and return to the UI. I’ll repeat the process until I’m done with the files that contain messy changes. At this point, there are usually just a few remaining files that need to be looked at. I’ll use the same process to check them off as well.
Eventually, I’ll have checked off all the files. At this point, I’m typically feeling really good about my changes. Sometimes though, I’ll want to repeat the exercise again. In this case, I’ll mark every file as “unreviewed” and start fresh. This time, I try to be more intentional about anticipating feedback. I also take the opportunity to call the reviewers’ attention to specific parts of the code I want to discuss by adding comments. Adding my own comments is the one thing I’ve mentioned that doesn’t directly mitigate feedback. It is such an effective way to enable constructive feedback, though, that I couldn’t help but mention it.
Other Gains
In addition to receiving fewer comments on my PRs, I’ve also observed the following benefits: Code reviews go smoother and I receive fewer requests for changes. As a result, I do less context switching as I don’t often need to set down new work to fix things on my PR. My code tends to contain fewer bugs. I am to stay more focused. I’m able to be more productive. I have greater confidence in the quality of the work I do. For all these reasons, I encourage everyone to give iterative self-review a try.