Code Reviews Are an Investment in Your Future Happiness
By: Robert Horvick
Tags: Best Practices, Software Engineering, Teamwork, Code Review, Software Development

In spring of 1998 I was an intern at Great Plains Software working on the QA team. I had been there about 4 months and contributed thousands of lines of code to internal tools, but nothing to the customer-facing product. I loved working on the internal tools but I really wanted to put something into the “real” product.

I had discovered a small bug in the UI of our commercial product and even though I didn’t work on this team, decided I wanted to fix it. I debugged through the offending C code, found the errant function, corrected it and verified everything worked. Ready to checkin, that negative voice in the back of my head chimed in and said “You’re about to break something and everyone is going to know it was you!” So I stopped, printed out a diff of my changes and walked over to my co-worker Todd’s desk to ask for his opinion. Todd was a talented and experienced engineer who had always treated me with kindness and respect. He looked it over, gave me the thumbs up, and encouraged me to check it in. With a renewed sense of confidence I went ahead and checked in my first change to a customer-facing product.

I didn’t know it at the time, but I had just stumbled onto one of the most powerful tools in software engineering: peer code review.

Since then I’ve participated in thousands of code reviews. Most were quick and painless. A few were neither of those. But all of them were valuable and each one made the product, myself, and my team, better.

Why We Do Code Reviews

Code reviews are a great way to find bugs. In “Code Complete”, Steve McConnell shares several examples of code reviews directly contributing to a dramatic reduction in errors per-LOC (e.g., IBM’s Orbit project — 1% of expected defects), increased productivity (14% at AT&T), and cost savings ($25,000 per defect at JPL).

Finding defects before they make it into production is the most important outcome of code reviews. But, especially for the reviewer, it’s not the only outcome and, sometimes, not even the goal.

Code Reviews Make You a Better Engineer

Photo by NESA by Makers on Unsplash

When I talk with my team about their long-term development goals there are three consistent themes:

Learn more about the company’s projects and architecture Get better at Scala/Spark/Python/whatever Improve design and architecture skills

Code reviews can help move the needle on all of these.

If you want to learn more about a project, participating in code reviews give you an opportunity to pull threads, ask questions and see how things work in the context of a single change. You don’t need to be knowledgable about the project to review changes but you will become more knowledgable as you do.

If you’d like to improve your knowledge of Scala, start reading more Scala. Read with the intention of understanding. Look for syntax, idioms, or patterns you haven’t seen before. Take the time to understand them and if necessary, ask questions. I love it when people ask questions because I know I’m about to teach something or learn something.

Code reviews can also help you hone your design and architecture skills. As you are reviewing, think about more than just syntax and line-by-line correctness. For example, you could look for what design patterns are in use, if the new API is really addressing the customer’s problem, and whether or not the code is testable.

As you learn to recognize good and bad patterns, you’ll begin to see them in your own code. The more code you review, the better your code will become.

Code Reviews Make You a Better Teammate

Photo by Randy Fath on Unsplash

Todd didn’t have to take those 10 minutes to look over my code. He could have said he didn’t know that area, that he was too busy, or that there was no policy that I had to have my code reviewed. Had he done that I could have just checked in.

He did it because he understood that we were a team moving towards a common goal and we’re most successful when we get there together.

Doing code reviews takes time. Time you might prefer to spend on “your work”. Some weeks it will be a few minutes and some it will be a few hours. That’s OK. It’s important that we take the time to help our teammates.

It can be hard to compare “time spent” versus “time saved”. Time spent reviewing code is tangible. It can feel like you’re focusing on someone else’s needs while putting your own to the side. It’s not until a bug makes it into production that “time saved” becomes measurable. The 20 minutes that wasn’t spent in reviewing a change can become a service outage, hours of debugging and patching, and the erosion of trust with your customers.

Performing thoughtful code reviews is an investment not only in yourself, but by reducing the number of critical incidents that need to be addressed, an investment in the overall health and moral of your team.

Code Reviews Are Not Optional

I work at a SOC2-certified organization. This means we have a documented engineering process we follow and code reviews are a part of that. If we fail to do them, we don’t just miss out on the benefits of improved code quality and individual growth, we run the risk of failing a SOC2 audit and losing our certification.

No Rubber Stamping

Image from Pixabay

There is a direct relationship between how large a change is and how long it should take to perform a meaningful code review. How much time is needed will vary person-to-person and change-to-change. I can’t tell you how long it should take you to review 200 lines of code changed over 18 files, but I can tell you it will take more than 30 seconds.

When I see a request for a code review and less than a minute later it has the necessary approvals to merge, that raises a red flag that causes me to look deeper.

What I hope to see is a comment that says “Arial and I went over this change in person, everything looks good!” This tells me an appropriate review was done in-person. In-person reviews are awesome and adding that comment lets everyone know what happened.

But surprisingly often what I see is nothing. Just an approval added far faster than should be possible without a comment providing context of how it was done so fast. It got rubber stamped.

This can happen for a variety of reasons, but the most concerning to me is that this person doesn’t see the value in code reviews so they just click “approved” allowing everyone to move past this process and get on with their day.

Don’t be that person. It’s lazy, it’s inconsiderate, and it’s a violation of the trust your teammates and customers put in you. And if you’re a manager, you have an obligation to be actively involved in the process by perform review reviews.

Code Reviews Need Exposure

Photo by Mimi Thian on Unsplash

On my teams I ask that the default audience for every code review be the entire team. The intention is not that everyone should review every change, but rather that everyone should have the opportunity to.

Keeping the audience wide ensures that everyone can benefit from the review. If you only include the SME and a technical leader, the rest of the team does not have the opportunity to learn and grow.

The flip side of this is that you, as the change author, need to be thoughtful about whose approval is necessary. If you are making a change in a new area, the SME for that area should probably be a mandatory approver. If you are touching an area that spans multiple teams, a representative from those other teams should also be mandatory.

Suggested Practices

☐ Do require pull requests

Use repo-level policies requiring pull requests when making changes to key branches (e.g., dev, master or release).

☐ Do use default and mandatory approvers

Configure repos so that every member of the team that own the repo is a default reviewer. Add mandatory reviewers as necessary to ensure SMEs and experts have their feedback heard.

☐ Do tell people what they are about to review

If you are already writing meaningful commit messages, those might be enough. But if more clarity could be beneficial, adding a good pull request description will take just a few moments and will make it easier for the reviewers to add meaningful feedback.

☐ Do plan time for code reviews

Planning time for code reviews into your schedule will help code reviews feel less like burdensome overhead and more like a normal part of the development work flow.

☐ Don’t drop code bombs

Keeping your pull requests to a manageable size demonstrates respect for your reviewers’ time and makes it more likely they will give a thoughtful review. If it is not practical to split a large pull request up, good commit hygiene can help by allowing the reviewers to approach the pull request a one commit at a time.

☐ Do review early, review often

Getting a review out early can give people more time to perform a thorough review and allows people to give feedback early enough in the process that you can actually implement it. GitHub’s draft pull requests can make this easier.

☐ Do respond to comments

If someone asks a question, makes a suggestion, complains, whatever … respond, and let them acknowledge the response (as appropriate), before merging. If the message does not warrant a response, clicking “Like” is a great way to acknowledge the feedback.

☐ Do pull, build and test

When reviewing code you don’t understand, it can be helpful to pull the change and step through it while it runs.

☐ Do review the tests

Don’t just look for the existence of tests — review the tests thoroughly. This validates that you and the author have a common understanding of the change’s intention, that the common and edge cases have been considered, and that any new or changed APIs read and function as you’d expect.

☐ Don’t be a jerk

Providing critical feedback is not a free ticket to Jerkville. Delivering feedback with empathy and respect is important to a healthy team culture.

Be Like Todd

When I see code review requests now, I try and remember what it was like that first time I asked for a code review. Despite my anxiety about what Todd would say, I knew that I’d rather face critical feedback before I checked in than after. While this was one of my first interactions with Todd, it left a lasting impression. In a few short minutes he demonstrated respect for me, for my work, for our for the team, and for our customers.

I encourage you to use each code review request as an opportunity to demonstrate that same respect to yourself and those around you.