Intended Audience: software developers
TL;DR Every software developer should establish their own definition of ready for review. Doing so will help them produce high-quality output, improve their coding skills, and save time, thus building their reputation as a skilled and reliable professional.
Haste Makes Waste
Before starting my first job as a software developer, I knew a bit about coding but nothing about software development. Initially, I needed constant help from my colleagues. After about six months, I could finally develop small bits and pieces of the software without inordinate levels of help. I felt competent.
Unfortunately, this newfound competence had a drawback: I was hasty in submitting my code for peer review. The minute I got the code working, I’d add a “ready for review” label. As a result, the code I submitted for review was sloppy. Only after submitting it for review would I skim through the diff and start noticing my mistakes. I often stood up from my desk to shout to a colleague, “Wait! Don’t review that yet! I need to change something!” This pattern was so consistent that, after a while, no one would even consider reviewing my code without first waiting at least ten minutes.
One day, my boss came over to my desk. “Why don’t you write a checklist of the mistakes you commonly make?” he suggested, “And then look at that checklist before you put a PR up for review?” (PR stands for pull request.) I ripped a sheet of paper out of my notebook and jotted down a bunch of my usual mistakes. From then on, before submitting code for peer review, I’d run through the list and check my code against it. Whenever a reviewer found a new type of mistake in one of my PRs, I’d add it to my list.
I’d love to say that I stopped prematurely submitting PRs for peer review after that. But the knee-jerk reaction to getting code working had become a habit by then, and it took a while to break. It wasn’t until I worked with someone who sent me sloppy code to review that I fundamentally changed my mindset.
More Info: Pull request |
Reviewing another developer's unpolished code
At a subsequent job, I worked alongside a developer who approached software development very differently than I did. Let’s call him Alex. While I see software development as a craft, Alex viewed it as a means to an end, with the end product being the main focus.
Alex submitted code for peer review with typos, incorrect formatting, confusing variable names, and no error handling or unit tests. This annoyed me. Alex had over 20 years in the industry. I didn’t think my time was well spent commenting on issues he could have caught and fixed himself. But he was focused on operationalising the product, adding more features, and attracting more users—not on code quality.
Alex's code was so messy that it was hard to see past the chaos and understand what the code was actually doing. I often ended up cleaning it up myself (on a local branch) just to make sense of it, but by the time I could finally grasp the logic, I had little energy left for a thorough review. This experience taught me a valuable lesson: reviewers have limited energy, and clear, thoughtful code is essential for effective collaboration.
I wanted to ensure my code, unlike Alex’s, looked polished and professional. I wanted to respect other developers’ time. To achieve this, I began meticulously self-reviewing my pull requests before submitting them for peer review. I realised I could get a more effective review by preserving the reviewer’s energy for the feedback that mattered. This meant I would also learn more from the review feedback—it wouldn’t be feedback on mistakes I would have caught if I hadn’t rushed. Instead, it was feedback on actual gaps in my knowledge. Feedback like this would help me level up as a developer and would also improve the codebase.
I no longer rushed to submit my code for review. I did almost the opposite. I took my time making sure that the code was as good as I could make it on my own. I was lightyears away from the junior developer I’d been back at my first job, overeager to submit code for review as fast as possible.
10+ years on
It’s a waste of both my and the reviewer’s time to leave any errors in a PR that I can find and fix myself. Humans have limited attention spans and limited amounts of energy. I want my reviewer to find the issues that I can’t. I want the resulting code to be better than any code I could have written alone.
Karl Wiegers says it best in the first chapter of his 2002 book Peer Reviews in Software: A Practical Guide: “In a multistep process such as software development, the quality of what comes out of any process step is limited by the quality of the inputs to that step.”
More Info: Karl E. Wiegers |
A Definition of Ready for Review
The checklist I created at my first job was an example of a definition of ready for review (thought I didn't think of it that way at the time). If you’ve ever used the scrum approach to project management, you might be familiar with the following terminology:
a definition of ready
a definition of done (DoD)
Following that terminology style, I want to introduce the term "definition of ready for review" to the industry. Shared terminology is essential, and I want this to be the name of this concept industry-wide.
More Info: Scrum |
A ready-for-review checklist
A checklist is one of many ways to present a definition of ready for review. Creating a checklist, like I did back at my first job, is a great way to increase the quality of your code and avoid wasting your reviewer's time. My ready-for-review checklist can be found here. Feel free to use it as a jumping-off point for your own checklist.
A living document
A definition of ready for review is a living document. It will evolve as it is repeatedly applied. Whenever I receive feedback on a PR, I consider whether that feedback can be added to my definition. Sometimes, I add checklist items specific to a particular project or workplace. Over time, I get rid of items that add no value.
Make it visible
You can create the most exhaustive definition in the world, but if you can't easily access it, then it is useless. I like to print my checklist and tape it on the wall next to my desk. This method works for me, but what works for you might differ. You may prefer to keep your definition in a notes app on your phone. You may like it in a spreadsheet format. Find what works for you, and run with it! (And do feel free to share. It’s always helpful to see how other people improve their workflow.)
Shouldn't you address some of these issues before coding?
You might have noticed items like “user analytics are being captured” and “text is provided for screen readers” on my checklist and thought, “Isn’t it a bit late in the process to start thinking about this?” It is. Ideally, these items—and others on the list—should be considered before coding begins.
The checklist is a safety net to prevent submitting incomplete code for review. While a robust process aims to minimise surprises after coding, occasional human errors can occur, which the checklist helps to catch. Better late than never!
What about reviewing "early and often"?
You have probably heard the saying that feedback should be solicited “early and often”. Early and frequent feedback saves us time in the long run. But how do we reconcile that with a strict definition of ready for review? You ignore the checklist and ask for peer code reviews before your PR is complete while specifying that the PR is still a work in progress. Many software development collaboration tools include a “draft” feature which facilitates this. Read more about early code reviews here.
More Info: Draft PRs |
Benefits
A definition of ready for review offers numerous benefits.
Produce high-quality output
Establishing a formal definition decreases the number of defects that exit the coding phase. This means the output of the coding phase is of higher quality. This high-quality output then becomes high-quality input to the peer review phase, which benefits:
you — by saving you time during the peer review phase
your reviewer — by saving them time during the peer review phase
everyone contributing to the codebase — by increasing the quality of the codebase that the code eventually gets merged into
Improve your coding skills
A definition of ready for review not only enhances the peer review process but also fosters continual improvement in your coding approach. If when you run through your definition, you discover significant items missed during coding, this indicates a gap in your coding approach. Take these insights and use them to refine your approach. This iterative process ensures thoroughness in your work and reinforces good coding habits, ultimately enhancing the quality and efficiency of your contributions.
Save valuable developer time
Each defect in your PR triggers a series of interactions between you and your reviewer. Even in the simplest case:
The reviewer inspects the code, identifies a defect, and provides feedback.
You read the feedback, implement the necessary changes, and confirm to the reviewer that it’s been addressed with a “fixed” response.
The reviewer verifies your fix and acknowledges completion with a “resolved” response.
Even this minor exchange consumes considerable time. In reality, the process often involves more complexity. The key takeaway is that issues like typos or placeholder code, which could have been caught with a checklist, contribute to unnecessary delays. Employing a ready-for-review checklist can eliminate these interactions and ultimately save valuable developer time.
Build your reputation as a skilled and reliable professional
Reviewing your work carefully before sending it for peer review helps build your reputation as a skilled developer and makes you a more desirable collaborator. Your colleagues will appreciate that you don’t waste their time with sloppy code.
Everyone makes mistakes, and some errors will inevitably slip through despite your best efforts. Human error is understandable.
However, mistakes resulting from carelessness, which could be avoided with a more thorough self-review, a ready-for-review checklist, or other adjustments to your coding process, are unacceptable. They waste your colleagues’ time and show a lack of respect for their efforts. Remember, your co-workers are not there to babysit you. Working sloppily will make other developers reluctant to collaborate with you.
Developer Action Items
Take 5 minutes to write down the items you currently check before submitting your PR for peer review.
If you have never reviewed your own code before submitting it for peer review, write down the mistakes that reviewers commonly find in your code.
Even better, look back at the feedback you received on your last 10-15 PRs. See if you can identify any patterns. Add commonly missed issues to your personal ready-for-review checklist.
Check whether the team you work with or the codebase you contribute to already has a shared definition of ready for review.
Consider using this definition to guide self-review before submitting any PRs for peer review.
If that definition is not already in checklist form, consider making it a checklist for personal use.
Alternatively, use it as a starting point for creating your checklist.
Post your checklist somewhere where you can easily access it when you need it.
Share your checklist, or just a few items from it, in the comments below!
Stay tuned for my next post, A Definition of Ready for Review: Part II, where I’ll discuss the importance of establishing a shared definition of ready for review within your team.