Code review observations are not failures

A code review observation can be one of the small mistakes that everyone makes, but cannot see by staring at their own work. These mistakes are normal, not failures. If you don’t make any mistakes, you might actually be an android.

A code review observation might be an opportunity to learn something that a colleague knows, but you don’t, perhaps about how the system works, how the team approaches development, how to use a specific technology or just about programming in general. If you don’t have anything to learn, then you are probably the deity of a recognised religion.

Code review observations occasionally contain specialist knowledge that you don’t need to know, because it’s not worth having more than one or two people think about it. You don’t really want to know everything that someone who’s been a subject matter expert for ten years knows, or everything that the local expert in a technology we hardly use knows.

A code review observation can be a detail that makes the difference between the code getting slightly better instead of slightly worse. The Boy Scout Rule applies to all of the small things that aren’t quite right yet - spelling mistakes, UI inconsistencies, missing comments, awkward variable names, hard-to-read code. Most importantly, there’s no `trash ownership' - it’s irrelevant if it’s not `your' empty beer bottle by the camp fire*.

A code review observation is sometimes a nudge towards the desired technical design, putting the code back on track. There’s always more than one way to do it, but when you’re working at the code level you cannot expect to remember all of the constraints that determine the right technical design, or even what the current design is. This wouldn’t matter so much if you re-read the system’s technical specification before changing code, but there isn’t one. Not any more.

Finally, a code review observation might even be that most basic of things: a proper functional bug, when the code does exactly what you wanted it to, which is the wrong thing. However much agile software development works to delay detailed functional design and shorten cycle times and feedback loops, once you’ve committed an idea to code its worthing finding out what’s wrong with it sooner, rather than later.

I suspect that if you’re not doing code review on your current project, it’s at least partly because you don’t like it much. Either way, you’re missing out, so perhaps it’s worth thinking about other approaches and whether changing the way you think about it will make it more appealing. Meanwhile, the next questions are:

How much time should you spend on code review? Not much, and certainly less than on testing, but not none either.

As with writing system documentation, a small amount of effort - perhaps a few of hours per week - can have a big impact. Additional hours quickly suffer from diminishing returns. A thorough code review takes more like half an hour than half a day.

From the perspective of a single pull request, ten minutes rather than hours are probably enough to discover the important things worth improving, and more useful than however much additional time you might spend. Besides, effective code review requires more concentration than you can keep up for very long.

There’s no rule for an exact amount of time to spend on code review, or a maximum, but perhaps there’s a neat rule of thumb waiting to be discovered. A good starting point might be to spend a quarter of each user story’s development time on review-and-test, and a quarter of the review-and-test time on code review. The more important thing is to decide whether this is the right amount, and adjust it so that you’re getting value for the time you spend.

There is still one way that more review time can be useful: review by a second person. Complex logic benefits from review by a domain expert, while a different team member may have more input on technical design. Even so, it’s probably better to just choose the more suitable reviewer, and to leave the other kind of review for the next time the same code comes around.

Code review doesn’t need hours at a time or several people because the code doesn’t have to be (and won’t be) perfect in one go. Continuous incremental improvement is more effective: when applied to frequently-changed code the result is that the code that has the most maintenance becomes the most maintainable. The most effective code review consists of frequent but short focused bursts of concentration from a variety of people.