Table of contents
The beginning: introducing code reviews
What is a code review?
Code improves with multiple reviews and revisions, and this process isn’t something that can be done alone. Spotting errors in code design is difficult at the best of times — and the closer you are to the work, the harder it can be to critique. That’s where code reviews come in.
In short, a code review is where one or more developers review someone else’s code to make sure it is appropriate and sufficient for the task at hand. It is carried out once the coder deems the code to be complete, but before Quality Assurance (QA) review, and before the code is released into the product.
Code reviews are done by hand, based on the expertise, wisdom, and judgment of the person or people doing the code reviews. These reviews are supplemented by automatic, mechanical reviews which look for specific, line level issues, generally undertaken by linters or other tools.
Each version control system (GitHub, GitLab, Bitbucket) uses different terminology for code reviews. For example, in GitHub, coders create a pull request once their code is ready for review. They may also identify one or more people to review the code, or a manager could select people to serve as code reviewers, or anyone can volunteer.
A code reviewer leaves feedback either for the pull request as a whole, or individually through comments. A single pull request can have 1-100+ code review comments but less is definitely more here. It’s highly recommended to create pull requests small enough to only need 1-3 comments.
Code reviews can cover a range of topics:
- Whether the team’s style conventions are followed (see below for a broader discussion of linters and code reviews)
- Whether the code meets code quality characteristics, such as readability, efficiency, and security
- Architectural approaches
- Domain-specific topics, that is, what the code’s use is (FinTech, DevOps, space exploration, etc.)
- Methods for integrated third-party code
- Potential security risks
If the Reviewer determines that the code is of sufficient quality, they approve the code and it typically progresses to a QA review.
If the Reviewer thinks the code may not be sufficient, they leave comments, questions, suggestions or directions and send the code back to the Author. Sometimes no additional coding is necessary– the Author explains their point of view to the Reviewer. More commonly, the code is changed. This process repeats until the Reviewer(s) determines the code is appropriate and sufficient.
Code reviews and follow up discussion are stored in the version control system. Anyone with access to that repository also has access to the code review comments and discussion.
How common are code reviews?
Code reviews are very common. In fact, it’s a practice you’ll find in almost every software development business.Approximately 90% of mid-size and large organizations use code reviews. Smaller companies clock in at an estimated 80%.
There are tens of millions of code reviews every day, just on GitHub alone.
Using some conservative math, at least one hundred billion code review comments have been created in the last decade alone.
Each one of these code review comments is a moment of feedback to a coder on their craft. A developer can expect to receive at least 250 highly individualized moments of feedback per year through code reviews and 7500 over the course of their career. Some receive more than 20,000 pieces of feedback.
Why are code reviews important?
The benefits of code reviews are threefold: they support code quality, they improve developers, and they uphold the craft of software development.
First, code reviews reduce the cost and risk of low code quality
Code reviews prevent technical debt, such as bugs in production, security risks, or code that is harder to maintain.
Low code quality is expensive for the business: it causes slower roadmap development, leads to developer turnover. And lower code quality is risky– just check the news for the latest impact of a security breach from coding practices.
Your executive team is already likely thinking about code quality. Accenture found that “C-suite executives say technical debt— the cost to rework IT to ensure the business thrives—severely limits their IT function’s ability to be innovative (70 percent), greatly limits their ability to migrate to new technologies (72 percent), and makes their IT function much less responsive to changes in the market (69 percent).”
Think of software development as a linear process moving from left to right. Beginning on the left, a software task is designed, then scoped, then coded, then automatically reviewed. After that, it is code reviewed– our focus. Once the code is updated to account for the review, it is QAed, and finally released to production.
The further to the left that improvements are made, the better: it saves developer time and QA time, and it improves the user experience. It is substantially more expensive, and more painful, to fix code after it goes to production.
As one of the first quality assurance steps of the software development process, code reviews deliver a great “return on investment.”
Second, code reviews sharpen developer skills and knowledge
Apart from saving time and money, there’s also human-centric value to code reviews. Based on the stats above, you can see that code reviews are the most common teaching, mentorship and feedback method for developers by far.
Code reviews can be an incredible mentorship opportunity, where the Code Author learns new development techniques and content about the domain of the code.
The Coder/ Code Author learns from the Reviewer, but the Reviewer also learns – by analyzing someone else’s code and then putting their insights into writing. Teaching is one of the best ways to learn.
These teaching / mentorship moments then have many follow-on benefits:
- Happier developers – giving developers opportunities to grow and learn is one of the best methods to keep Engineers happy, since most Engineers are deeply curious, like to teach, or both
- Faster onboarding for new developers, or third-party developers
- Knowledge sharing – to make sure that multiple people in the organization understand each section of the code
Third, code reviews safeguard the craft of software development
We’re going to get religious here for a moment, so stay with us…
Code is a craft, not a competition.
It is a craft based on standards of knowledge and excellence passed down from senior engineers to juniors.
It is a craft built on feats of design. Building something that works, the right way, is its own reward — and challenge!
It is a craft where the ‘making of’ matters — how you do what you do can matter as much as what you do. Churning out wooden chairs on a factory assembly line is not a craft, custom building one by hand is.
This craft has delivered incredible opportunities to the world: making peoples’ lives better by using software, and creating amazing career opportunities and passion projects for tens of millions of people.
At Sema, we believe this craftsmanship comes with a responsibility: a responsibility to give back to the craft of code.
And code reviews are, in our view, one of the best ways to do it. It allows us to be good stewards of our craft — ensuring that wisdom is shared, that junior developers are advancing in their knowledge, and that the code is built the right way.
We’re not naive. We know that advancing deadliness, sales demands, and company pressures mean that code will always have technical debt. Code can’t be perfect, nor should it be.
But we are here to make it easier to advance the craft through better reviews.
It sounds like there's a lot of benefits to code reviews. Is there a catch?
There’s no catch, but only a few organizations are able to realize the full benefits of code reviews, even if there is a proper process “on paper.”
This can be chalked up to a number of factors:
- Developers are frequently under a great deal of time pressure to deliver new features/ functionality, or fix bugs – coding as opposed to reviewing code. This pressure can include code review timebeing unaccounted for during sprint planning, and not being recognized during annual reviews
- The rise of work from home and distributed teams mean the code reviews are asynchronous. It can be much easier to review code when you are sitting next to the author, so they can ask follow up questions and understand the reviewer’s tone.
- Underinvestment in training – code reviewing is a skill that needs training and mentorship
- Tooling to make code reviews more robust and seamless has not kept up with other developer tooling
As a result, organizations are missing out on opportunities to better support code quality, knowledge transfers, and the craft of coding.
How would I explain the benefits to a non-technical CEO and others in the organization?
Get ready to bridge the technical divide! Here’s how we would explain to a non-technical CEO why code reviews are important.
First, you will lose engineers without a culture of mentorship and learning.
Engineers are among the most in-demand positions for all companies, across the globe. COVID and Work From Home sped up the globalization of the talent market for engineers. Companies need to aggressively invest in their Engineers. If you’re not actively building a great place to work, you’re on the losing end of the war for talent.
One of the ways to build a great place for engineers to work is to shape an environment that supports mentorship. Being able to learn and explore on the job is no longer a “perk” but a requirement. Engineers are deeply curious and code reviews are a great way to facilitate a learning culture.
Second, you will fast track the effectiveness and productivity of new engineers.
If you are hiring new engineers, or bringing in third party development shops and freelancers you want to ramp them up as quickly as possible. Code reviews fast tracks the onboarding process.
The difference between an effective and ineffective onboarding is 6 months or more of lost productivity. Unproductive onboarding means wasted financial resources and time, slower time to market and ultimately, losing pace with your competitors.
Third, engineering effectiveness and velocity will be lower without code reviews.
Your CEO will no doubt have heard the concept of “10X developers,” rare developers who are significantly more productive than everyone else. Whether or not that’s true, the idea of the 10X developer is informed by a substantial uplift in skillset – and so they are better able to contribute to the code and the team.
Think of code reviews as a means to 10X not one developer, but many. It’s great way – in our view, perhaps the best way – to continuously improve the quality of the entire team, not just an individual. This is because coding is fundamentally a craft, not a competition– a rigorous skilled activity that requires learning from more experienced experts, and one that requires deep knowledge and concentration. The greater the investment in growth and learning, the higher their effectiveness will be.
Gartner says the productivity difference between low and high performing engineering teams is 53%. To us, that estimate merely scratches the surface.
The Golden Rules of Code Reviews
What are some of the ways that a code reviewer can carry out a good code review? Aka, tips and tricks to create effective code reviews.
There are six Golden Rules of Code Reviews. If you've ever been involved in feedback training, some of them might sound familiar. And that's exactly right – code reviews are just one specific format of giving feedback in a particular domain.
First, remember that there is a human being on the other end of the review.
The first Golden Rules of Code Reviews is simple: Review other people’s code like you’d like your own code to be reviewed.
Code reviews should:
- Be kind– even if there’s room for improvement, the message can be delivered with empathy
- Be clear– make it easy for the reviewer to understand what you are saying. Importantly: this means that if you have constructive feedback to give, be direct about it. Avoid a “crap sandwich” that starts with positive feedback about the code, even if it’s genuine, before getting to your suggestion for improvement.
- Be specific – The more granular your feedback can be, the more helpful it is to the Author.
In practice, this can be hard to do when so many of us are working remote or hundreds or thousands of miles away from each other.
To make sure you are communicating correctly, read your code review to yourself out loud and ask yourself, is this something I would want said to me? If not, think about changing the tone or content.
Second, never tell someone that the code needs to be fixed without giving suggestions or recommendations on what to fix or how to fix it.
This is the second Golden Rule of Code Reviews.
Not sure why? Imagine someone came to your home and said, “I don’t like your decor. Fix it.”
It is incredibly annoying.
It is never a good idea to write “Fix this” without giving more explanation. Why does it need to be fixed? What suggestions do you have to fix it? How might someone figure it out?
On behalf of the Code Review powers that be, we will personally come to your home to rap your knuckles if you ever leave a code review that only says “Fix this” or “Do better.”
Third, assume good intent.
Code may not be written how you would write it. Let’s say that more clearly: code is rarely written the same way by two different people. Code is a craft, after all, not a task on an assembly line.
Tap into a sense of curiosity and appreciation while you are reviewing – curiosity to try to understand what the reviewer had in mind, and appreciation for what the Coder did or tried to do.
Fourth, clarify the action and the level of importance.
If you are making an optional suggestion, for example, a “nit” that isn't necessary before the code is approved for production, say so, clearly.
If you are wondering why the person made a certain choice, but it doesn’t affect whether the code should make it to production, say so, clearly.
If you are confident that the code needs to be fixed before it is ready for production, say so, clearly.
Pro tip: when we are writing, we frequently think that our intent is clear. After all, we know what we are trying to say. It’s worth remembering our writing may not always be clear to the reader so make sure that your most fundamental guidance is clear.
Fifth, don't forget that code feedback – and all feedback – includes praise.
It goes without saying that the key benefit of doing code reviews is to make the code better, and fix issues.
But that's only half of it. On the flip side, code reviews present a great opportunity to say thank you and to appreciate the work of your colleagues.
If someone has written particularly elegant or maintainable code, or has made a great decision about using a library, let them know!
At Sema, we say it is always the right time to give positive, specific feedback. Of course, we walk the talk when it comes to code reviews too.
How should an Engineering team support effective code reviews?
Code Reviews & Psychological Safety
Disputes, conflicts and dissenting opinions are all part and parcel of the code review process. Because code reviews are based on trust, psychological safety is a critical component.
What’s psychological safety?
Psychological safety is about colleagues feeling safe and trusted, knowing there is room for mistakes and that bad news can be shared, and generally feeling confident that the organization has your back. Studies at Google and elsewhere have demonstrated that psychological safety is one of the most important factors to make teams be successful.
It makes sense– if you are constantly worrying about whether someone’s out to get you, you are going to be investing significant time and emotional energy in protecting yourself, rather than creating. And you’ll be suggesting far fewer ideas, or taking far fewer risks, that could advance the team.
Everything you are doing to work towards greater psychological safety in general at your organization and your team has applicability to code reviews, too:
- Reduce the negative consequences of delivering code that needs to be fixed. We can’t say “eliminate” the negative consequences; after all, teams are here to build great code that meets requirements. But framing cost reviews as teaching moments, not judgment moments, make it
- Regularly canvas the team, especially junior developers and others who might be worried they have less standing, to understand how the code reviews are making them feel.
- Review a sampling of code reviews regularly across all reviewer-coder pairings, to look for positive or worrisome trends based on their tone and conclusions.
- Offer training and support, not judgment, to colleagues who may need more training and support in creating code reviews that protect psychological safety.
- Finally, we recommend that continuous violators of psychological safety, in code reviews and elsewhere, should be asked to leave the team. We don’t believe that any single coder or colleague is more important than making sure that everyone feels enabled to do their best work.
Clear process
Make sure that the process for code reviews is articulated, clear, codified, taught, followed, and reinforced.
Especially while teams are dispersed, it might be helpful to have a “cheat sheet” of the basics of your code review process easily available – such as, pinned to the development Slack channel.
On top of that, the organization should be clear about when code reviews should be done and who should do them – see below.
Fast turnaround
Code reviews are a responsibility that should always be taken seriously — and take first priority. Someone's first task is always to review other people's code before writing one's own.
The reason for that is that unblocking someone else's work makes others on the team more effective. If you are working on your code, instead of reviewing someone else's, then it becomes a blocker. If you review their code, then work on your own code, you are unlocking your team’s potential. Remember — it’s a craft, not a competition!
Intentional and structured approach to code reviews
There is “no one size fits all” answer to this. It varies by codebase, organization size, and team preferences.
When a company is starting out, code reviews should look different than during rapid growth, or product maturity.
Here’s a quick guide to figuring it out for your team and development stage:
- If a product is just starting to be built, at the earliest stages, such as during a hackathon or simplest minimum viable product, then code reviews are not necessary. At this stage, they only get in the way. The team should just figure out what the functionality should be created and do their best.
- After that stage, code reviews ramp up in importance. Early stage companies might want to pick one person on the team to do all of the code reviews. This has the benefit of simplicity and speed, but comes at the expense a shared and varied learning experience.
- As a company grows, more people should be performing code reviews. As a rule of thumb, all senior engineers should do code reviews when a company is in the rapid growth phase. In this phase, we are assuming that speed is still essential.
- As the company matures, and as there is more capacity, code reviews should be carried out by seniors and mid level engineers.
- Finally, as the codebase becomes mature, and as the team has more capacity, all engineers including junior engineers should participate in the code review process. Note that the juniors will not only need training, but their reviews will also likely need a second evaluation by someone more experienced. Here, a major goal of code reviews is as a teaching tool for the junior engineers.
Clear coding standards, readily available
Next, if your organization has documentation about coding guidelines or content specific to your code, make sure it is readily available and accessible to the code reviewers so that they don't have to search everywhere for what to include. See a discussion of linters, below.
Give code reviews gravity
Make sure that code review work is as valued as coding — both activities should have equal weightage and visibility.
There are many ways to do this: from celebrating engineers who have done a lot of code reviews, to discussing code reviews at informal check-ins, to including contributions to code reviews as part of the annual performance process.
If code reviews are not important based on recognition, rewards and other consequences, it doesn’t matter what is said on paper.
Do you have a “great developer” who refuses to do code reviews or refuses to act on feedback from others? What happens to them? That’s one of the clearest signals to the rest of the organization about how much code reviews actually matter.
How can coders help with code reviews?
Code Authors have an important role to play for effective code reviews.
Keep pull requests small
Try to keep the pull requests as small as possible. When a pull request requires more than three comments— and especially once it reaches five — it is usually a sign that the pull request likely should have been broken up into smaller pull requests.
Be open to feedback
Remember, it can be just as stressful to give feedback as it is to receive it. Coding is a craft and it is hard to point out ways that someone else's hard work could be improved.
If you feel frustrated by feedback you received, pause before responding – perhaps put it aside and go for a walk / sleep on it and come back to it the next day. Is there some truth to the feedback that was shared?
The more open and appreciative you can be with feedback, the more ideas you will get from others, and the more you will grow.
Respond quickly – if you can
If you have a negative emotional reaction to the review, best to step away. As Oasis so eloquently sang, Don’t Write Back to a Code Review in Anger… or at least that’s how we remember it.
If you don’t have a negative reaction, deal with the review as fast as possible– answer the questions, make the changes, ask follow-up questions.
Context switching is a killer for coding flow. The goal is to minimize the time spent for you and the Reviewer thinking about this review vs. other coding work. If you can reply to the review just after the Reviewer completed it, you avoid the mental effort later for both of you to have to get back up to speed.
Switch to synchronous communication for any follow up
Code reviews are usually asynchronous, and can be completed thousands of miles apart.
In the Olden Days, when Dinosaurs kept using up the copier toner with jokes that really weren’t all that funny, a Coder could ask a question or a colleague by walking over to their desk.
Now we have many other tools, which are helpful up to point.
Now it’s time for the sixth and final Golden Rule of Code Reviews (you didn’t think we’d forget, did you? If the code Author has a follow up question to a code review, do it synchronously in real time, not asynchronously. Pick up the phone, start a huddle, walk over.
The reason is context switching. At this point, there will be three moments of focused attention on the code:
1- Author writing
2- Reviewer reviewing
3- Author internalizing the review
Asking clarifying questions about the review automatically means there will be a fourth moment:
4-Reviewer responding.
The goal of synchronous communication here is to avoid requiring a fifth, sixth, seventh, etc. moment of attention.
How can the rest of the organization, like Product and Sales, help make code reviews more effective?
Trust the process
Any 76ers fans in the house? Hello, we see you!
It can feel so urgent that a feature be added right now, or a piece of code pushed to production by close of business. We get that.
But skipping the step of a code review almost always makes things worse later – and sometimes, not all that much later.
Trust us: no user is happier with a buggy version of the code than with a more complete version in the next release.
Protect review time
The most essential thing that the rest of the organization can do is understand that code reviews are part of coding and time should be set aside in sprint planning and other kinds of work estimation.
As discussed above, code review “return on investment” is extremely high, and so organizations need to protect that time.
Organizations who estimate and plan engineering activities should include a buffer of 10% to 50% for code reviews beyond code writing, depending on the complexity of the code being written, the coder’s skill level, and the reviewer’s skill level.
Cement its importance
The point above about formal recognition and or “consequence management,” is as true for the rest of the organization as it is for the Engineering team.
If the CEO celebrates feature completion, does the CEO also celebrate code quality, developer mentorship, and code reviews? Does the annual performance process reflect reviews too?
Remember, an ounce of prevention is worth a pound of cure. Investing sooner in code reviews through celebration and recognition means avoiding more expensive outcomes later like technical debt and developer attrition.
How code reviews interact with other ideas, departments, themes
What's the relationship between code reviews and QA?
The QA team performs a review to make sure that the coding requirements are met, in particular requirements visible to the users. This could include visual components, functionality, or performance.
By contrast, a code review view looks at the innate or underlying quality of the code to make sure it is sufficient and appropriate quality for the stage of the business.
At Sema, one of our core beliefs is that the right level of code quality varies based on the stage of the product and the stage of the organization– and this is true for QA as it is for code reviews.
Code review and QA investments should increase at roughly the same rate.
If you’re building a minimum viable product or a hackathon project, QA can be done by the Coder or others on the team, and code reviews can be skipped.
As the product matures a little, we recommend adding some dedicated QA and code reviews by one other person.
Mature products should have extremely robust QA teams and processes, and extremely robust code review processes.
What about code reviews and linters?
Linters are software that automatically review the code, typically at the line level, for concerns about readability, code performance, or other suboptimal practices grouped under the category of code smells.
If your team finds a linter with style guides / best practices that work well for your project, and your team is OK with them, by all means, use them.
And the bigger the team, the more important it is to lint-- it makes communicating across the team that much easier.
Linters are not replacements to code reviews, however. When you are using linters, the code reviews can focus on other elements of the code– choices of frameworks, algorithms, data structures, for example.
What about code reviews and paired programming?
Paired programming is an extremely helpful tool in an engineering team’s toolkit, and should be applied where necessary. In particular, working with junior engineers and working on tricky problems are great opportunities for pair programming.
It's true that paired programming reduces the need for code reviews, because there are already two people looking at the code instead of one.
Still, we believe that code reviews should occur on code written with paired programming, because there are multiple other benefits: knowledge transfer so that a third or fourth person understands the code as well as teaching moments for others.
Don’t get us wrong — we are big fans of paired programming! You can read a great guide to it here.
How can I learn more about code reviews and related topics?
GitHub guide to code reviews: https://github.com/features/code-review.
One of our favorite sources for more training is a class by Curtis Einsmann It’s well worth it.
An important recent paper on bias in code reviews with steps towards reducing that bias: https://t.co/eyhxiKi7Kk
For more on psychological safety, check out subject matter experts Professor Amy Edmsonson and author and scholar Tom Geraghty.
P.S. Why did we just write a whole paper about code reviews?
As you might have guessed, we’re obsessed with code quality, supporting developers’ learning and growth, and the craft of coding.
And we think code reviews are one of the best ways to achieve this goal.
We’ve been building a code review tool for the last year. It integrates with GitHub and takes seconds to set up.
If you have read this far, you probably care a lot about code quality, too.
We’d love to hear what you think. Send us an email at cr@semasoftware.com and you can skip the waitlist.
