Code Review Beyond Meeting Rooms and Projectors

Editorial Note: I originally wrote this post for the SmartBear blog.  You can check out the original here, at their site.  While you’re over there, have a look at their Collaborator offering.

It must have been a decade ago.  I was sitting in a spaciously appointed conference room around a large, round table, surrounded by fellow software developers from my company.  Coffee and bright lights notwithstanding, we were all struggling to varying degree to keep alert.

The reason for our struggle was that we were spending the day doing a marathon code review, and we were barely halfway through the morning.  A representative of the team that had written the code was on hand, walking us through it, showing the code against a pull down screen with a projector.  We were being treated to file after file after file, in alphabetical order, in a text editor.

There were hours of this yet to go.  And yet, it was an unavoidable matter of due diligence.  In spite of our wandering attention spans, we believed this, as did our management.  Our company had contracted with a custom software vendor to write an application that our company would take over and maintain.  This firm had scurried off for 9 months or so, and they were now presenting “phase 1” to us.  This was our chance to raise concerns and provide input.  Theoretically, anyway.

As you can imagine, this was not an especially effective way to spend a day (or several, as it would turn out).  We technically saw all of the code that was being delivered, but it wasn’t as though this activity produced a lot of meaningful output.  There were some obvious reasons for this, such as the enormous batch of reviewing 9 months of code and the marathon, all-in nature of the session.  But there were also some issues related to tooling and process that were pretty limiting compared to what we have now.

10 years have elapsed since this yawn-inducing series of days I spent in review.  And, while you’re still going to be in trouble if you try meaningfully to review 9 months of a team’s code in a few days, tools and workflows have emerged in the interceding years that make code review much easier.  You should be taking advantage of them.

Asynchronous Review Capability

Back around 2006 when our epic review was taking place, CVS dominated the source control landscape.  Our vendor used it and so did we, but, naturally, we didn’t use the same centralized instance.  For the purpose of the code review, they had checked the source code out onto a laptop that they brought with them.  A combination of bandwidth concerns, IP paranoia, and lack of source control sophistication meant that the idea of somehow sharing this code ahead of the big hand-off was impractical.

And so, there we sat, 10 or more developers, all reading (okay, skimming) the same code at the same time.  This is beyond inefficient — it’s criminally expensive.  If you want to see just how expensive, go to this meeting cost calculator site and see for yourself.  That code-review-athon almost certainly cost the company more than $10,000.

In 2016, we have distributed source control systems, ubiquitous connectivity, and remote collaboration tools.  It would be entirely possible to have people review the code out of band and come together only to discuss important, conceptual matters.  Alternatively, it would be much easier to divide and conquer, setting 5 pairs of people to review 1/5th of the code each.

Semantic Review Aids

Another serious source of inefficiency (and boredom) during that code review was the fact that we were reviewing files in plain text.  If you’re a VI purist, that might sound fine, but most people have a faster time to comprehend with syntax highlighting.  But, for the purpose of code review, we can do even better than that.

Semantically aware diff tools can show you not only familiar syntax highlighting constructs, but they can also show you source code differences in ways that make sense.  They’re smart enough to recognize that you switched two methods in the file, instead of processing that as a giant jumble of random changes.  Reviewing walls of code is tiresome and incomprehensible diffs even worse; use tools at your disposal to gain clarity.

Static Code Analysis

Another tool to add to your tool chest is static analysis.  While this concept did exist a decade ago, it has been heavily refined and become far more ubiquitous than it was then.  On top of that, the tools tend to be lighter weight and easier to install than ever, so getting them is often just a matter of installing an IDE plugin or downloading something and running a wizard.

Static analysis raises the game in your code review substantially.  You won’t be squinting at a wall of code, wondering if it could dereference null or if it has too high a cylcomatic complexity.  You and everyone else will have answers to questions like that going into the review, and you can discuss what to do about them instead of whether they exist or not.

Granular Change Sets

I spoke earlier about how it might have been nice to divide and conquer, particularly when faced with reviewing an entire team’s work for 9 months.  With the asynchronous tooling, you can slice the codebase up by module or application layer or really, whatever you want.  But with modern source control workflows, it becomes really easy to slice things up by time.  Or, if not precisely by time, by sequences of alterations to a code base.

With old source control systems and old development practice, changes tended to appear in massive batches and lumped together.  Even when they could be tracked, it was common practice for developers, ahead of a code review, to keep manual lists of which files should be reviewed.  Absent that, the task was like boiling the ocean.

But today we live in a world where people are encouraged to deliver code early and often and where our source control schemes allow us easily to get back to code at a moment in time and to see who changed it, when, and how.  Take advantage of this capability and make your code reviews targeted, surgical affairs.

More Than Just Looking at Code

Code review comes from humbler beginnings — far humbler, even, than a bunch of developers sitting around looking at a projector in a conference room.  And that means that the practice has come a long way over the years.  It wouldn’t have come so far and proven so persistent if it weren’t valuable.  And because it is valuable, it has been surrounded by innovation.  Use that innovation to your advantage.  If nothing else, you’ll be able to spend more time on productive work and less time fighting to stay awake in meetings.