5 Steps to Create an Effective Code Review Culture

5 Steps to Create an Effective Code Review Culture

Anyone on a development team who contributes to a software project expects some sort of a code review process. The vast majority of engineering leads will tell you code review is important. The team will have a code review process set up that everyone is encouraged or required to follow.

The only problem? You’re more likely to get the standard “Looks good to me!” (a.k.a. “lgtm”) and approval, without any substantive feedback. It’s a missed opportunity for you to learn from others and to improve your code. The team also misses out on the many ways code review makes your dev team better.

Tuning your code review process towards providing valuable feedback significantly improves the quality of your code. Higher quality code is easier to maintain, has less bugs, is more secure, and saves money.

Think I’m exaggerating? On average, 42% of developers time is wasted on technical debt and bad code.

A team’s code review culture often goes unmentioned. This is surprising since many teams talk about its importance and require code review for every pull request.

Yet somehow they lose sight of the fundamentals. Effective code review is a critical component of accelerating the development velocity of your engineering team.

If done effectively, code review offers significant improvements in:

  • Product quality

  • Time to production

  • Developing engineers' skills

  • Reducing risk (from bugs and security vulnerabilities)

Most of the challenges of scaling an engineering team stem from the same root problem that plagues any organization – communication. With a growing team size, communicating effectively gets more challenging.

For a well-functioning team of engineers, code review is the most focused form of communication. Reviewing the work of your fellow engineers and learning/applying constructive criticism is an effective means of fostering a healthy engineering culture.

Here are five steps for improving your code review culture:

1. Encourage easy-to-review pull requests

Teams that encourage manageable pull requests gain faster code review turnaround times with more valuable feedback. Break apart larger, complex pull requests into smaller, simpler ones. A pull request with 2,000 lines of code changed and dozens of changes is nearly impossible to review.

When submitting pull requests, developers with a focus on code review should add a complete title and description. A quick glance at the title should be self-explanatory. Sorry, this means no more pull requests with the title “bug fixes.” The description should cover what was changed, why it was changed, and how the problem was solved.

Work on building a culture that submits pull requests that make it easier for a code reviewer to provide feedback.

2. Everyone on the team should review code

Watch out for the mistake of only having senior developers review code. Having only a few team members review is a missed learning opportunity for all. Not to mention that bottlenecking your code review flow with just a few developers creates a blocker for pull requests getting merged.

Naturally, a senior programmer providing feedback to a junior programmer will have the most impact on their learning and progression. Through this kind of mentorship, senior engineers can transfer knowledge or suggest a better way to implement a portion of the change.

However, the same junior programmer can also learn better practices and new ways of solving problems by reviewing the code of someone more senior. Don’t worry, just because they do a code review, it doesn’t mean they should also be approving pull requests. The goal should always be a focus on producing cleaner, high-quality code.

3. Ask questions, ask ‘dumb questions.’ Just ask questions.

The reality is there are two types of teams. One where engineers feel closed off from asking questions, typically from a history of unhelpful responses or a lack of trust. Or the second, where engineers feel open to asking questions at the risk of their ego. Which team do you think fosters the best feedback in code review?

If no one is asking questions, code review usually consists of reviewers blindly submitting “lgtm” and hitting the Approve button. When an engineer doesn’t feel comfortable seeking understanding, no one learns, and your code quality gets worse.

Build a culture that encourages a member of your team to ask why the code was written that way when they don’t understand part of the change. We want people to feel free to ask questions so both the submitter and reviewer understand how to improve their skills beyond this pull request.

Code review is one of the best ways to get junior members of a team up to speed. Encourage them to ask questions and understand what and why the changes were made.

4. Document coding style with a source of truth

I get it. You’re in a never-ending battle arguing for indenting with tabs instead of spaces. Formatting consistency matters. Attention to detail is what separates great products from mediocre ones. However, we should prevent these from ever coming up in a code review so your team can focus on feedback that matters.

Try to prevent all commonly debated, yet inconsequential questions with a programming style guide. Once you get all of the nitpicks out of the way and documented, the majority of your code reviews will be a more productive conversation. Documenting the preferred practices results in cleaner code that’s easier to maintain.

As new, commonly debated points amongst the team arise, document them in your style guide. This way the team has the debate and comes to the resolution once, instead of in every code review. Even better, build a linter or formatter into your workflow so the code automatically matches the standards in your style guide.

A programming style guide helps beyond reducing friction during code review. One of the principal advantages is that it fosters collaboration and team culture. Whether or not everyone agrees on every detail, they will know that this is what “we” do and this is why “we” do it. When onboarding new engineers, it also boosts their understanding of how to contribute consistent code.

5. What’s more important to you? Shipping fast or clean code?

All you need to do is ship all of your features well before your deadlines and a thorough code review for every single pull request. No pressure there!

Code review can seem like an obstacle in the way of shipping product to your customers. If you already have unit tests and QA then why does anyone need to review your code?

This discounting of the value of code review and clean code is a typical attitude when it becomes crunch time. Depending on the size of your product’s team and stability, your goals likely live somewhere along the scale of “ship fast” to “quality.” When the pressure is high, it’s tempting to forget that the quality established through code review has compounding benefits that speed up development.

How much will focusing on code review and code quality speed up development?

Perhaps unsurprisingly, engineers spend almost half their time on technical debt and maintenance issues. Imagine letting them spend more time on new features instead. Is it worth sacrificing time for code review now?

Having a strict requirement of code review for every pull request can help significantly in making your code more readable, future-proof, and bug-free. Over time this means less time spent on bug fixes and more time developing features.

About PullRequest

HackerOne PullRequest is a platform for code review, built for teams of all sizes. We have a network of expert engineers enhanced by AI, to help you ship secure code, faster.

Learn more about PullRequest

Brennan Angel headshot
by Brennan Angel

September 20, 2018