Building a culture of code review

One question that we see pretty often is how to create an engineering culture that embraces code review. It’s hard to overstate the benefits of code review, and engineering groups who aren’t doing it are missing a huge opportunity to improve the quality of their software, as well as get a lot of other benefits.

Jeff Atwood of Coding Horror summarized a lot of these benefits in his article Code Reviews: Just Do It. His only caveat was “The only hurdle to a code review is finding a developer you respect to do it”. If you’re a one-person shop, then that’s a very hard question, but most of us work with developers we respect: our coworkers.

Unfortunately, getting engineers to change their workflow and processes is a lot like herding cats: generally impossible, except in the case that it makes their lives easier (and then they’ll herd themselves). One of the best managers I ever had explained to me her observation that people only change if they want to, and so the best approach to effecting change is to work on making them want it.

The extensive benefits of code review make it an easy sell, but if it’s not introduced in the right way, it can create tension and resentment, which will kill any chance of adoption.

The easy answer to creating a code review culture is to build it in from the start. Many of the startups that I’ve talked to recently have incorporated some form of code review from day one. Fortunately, a lot of new companies these days are founded by people who have worked in an environment where robust code review is a given, and when they strike it out on their own, it’s just the most natural way to do things. If you’re forming a new organization (or even a new group within an existing organization), it’s the ideal time to build in good practices from the start.

Where it becomes a sticky, difficult question is when dealing with an established company with entrenched practices. How do you get people to change the way they work? Anyone who has ever worked with actual humans will know that bursting in the door and announcing a new process is liable to be met with groans, laughter, or silent resentment (and often all three).

Sneak it in through the back door

Joel Spolsky has a lot of advice on how to get things done when you’re only a grunt, and a lot of that advice works very well for adding code review to existing processes. Going back to the psychology of change, it’s easiest to ask people to do code reviews for you, rather than the other way around. Dropping in on a coworker and asking them to take a look at your code before you check it in is received much better than dropping in on them and saying you’d like to have approval power over what they’re doing.

When I started working on the Workstation team at VMware, we already expected code reviews for every major change, but the official system used email. After creating Review Board, Christian Hammond and I wanted to use it at work as well as home, and we set up a server for ourselves. For the first couple weeks, we just sent things back and forth to each other, while still using the old process for everyone else. As the benefits of improved tooling became visible to others, it took off, and before we knew it, we had people we’d never even met using it.

If you’re a manager, don’t force it

For those of you who might be reading who are managers of software engineers, and want to add code review to your development process, I don’t have a ton of advice, because I haven’t done a whole lot of management. The biggest thing I can urge is to go slow and avoid prescribing any particular behavior.

Educate your employees, maybe set up some tools, and then try to let things happen naturally. Making code reviews a part of the way you measure performance is a nice goal, but doing so when people are still trying to figure it out incentivizes the wrong behavior. The more structure and process that’s enforced at the beginning, the less likely that code review will actually take root, or if it does, it will be a cursory process to get the rubber stamp.

Always remember that it’s not about ego

Ego in code reviews is a big enough topic that we’ll probably tackle it in a separate post, but I think it’s also worth mentioning here. When people are new to code review, it can feel like a brutal, ugly process. It kind of sucks to expose your hard work and have people tear it apart. A healthy code review culture requires respect on all sides–people reviewing code need to remember that there’s a human behind the code, and people asking for code reviews need to remember that they are not their code, and it’s only through collaboration that we produce our best work.

Read More

PDF Review Beta

A little while ago, we announced that we were building document review features for Review Board. This will be available as a commercial extension in order to help fund the project. Of course, once it’s ready, RBCommons customers will get it as part of their normal plans. I’d like to show off a bit what you’ll be able to expect.

Since Review Board 1.6, you’ve been able to attach arbitrary files to review requests. For anything except images, the only way to view them was to download them. You could add general comments to these files, but for large things like a document, you couldn’t use the direct commenting that we’ve all come to love from the diff viewer.

With the PDF Review extension, when you upload a PDF file, it gets a thumbnail and a “Review” link.

review-request

Clicking on this file will open up the PDF Review UI, which has controls to navigate the document. The file is rendered directly in the browser with no plugins (which requires a relatively modern browser).

pdf-viewer

Like image review (and screenshots before it), you can add a comment to the document by clicking and dragging over the area that you’d like to talk about.

adding-a-comment

When you publish, the areas that you selected will be copied into the review along with the page number on which they occurred.

review

If you signed up for the beta program already, you should have received an email with instructions on how to install and activate this extension. If not, feel free to sign up and we’ll get in touch!

Read More

Making RBCommons more inviting

We’ve just deployed a change that makes it much easier to get your team set up on RBCommons. Until now, if you wanted to add a new user, you’d have to register an account first, and then add the username in your team administration dashboard.

Going forward, instead of registering an account first, you can just add the email addresses of each of your teammates. They’ll get an email with a special sign-up link, and once they create their account, they’ll be automatically added to your team.

admin-users

As usual, if you have any questions or comments, feel free to get in touch.

Read More