You Don?t Need a Code Review Template

What do you have in mind when you search or hope for a code review template?? I’ll bet I can guess.

You’re looking for something to guide you through the process.? In your mind, this probably takes the form of a worksheet of some kind.? The appropriate document should have a checklist of items for you to tick off and perhaps some free-form text spaces for you to make notes.? It will also guide you through the process in general.

I get it.? But you really don’t need this, even though it seems perfectly reasonable and inviting.

The Actual Life of a Code Review Template

Before I dive into the meat of?why you don’t need this document, let me talk about what will happen to it when you acquire it.

First, you’ll go searching and find something like this.? Then you’ll find a few more of those and put it together into your own list.? It will include items like the following:

• Each method should have a clear responsibility.
• Each method should also have no more than three parameters.
• Close any connections you open and dispose of any resources that need disposing.

And so on.

You’ll put this document together, and then you’ll stick it on your group’s SharePoint site, where everyone can see it and add to it if need be.? “It’s a living document,” you’ll assure everyone.

Your brand-new code review process will get off to a good start, with people participating and faithfully following the code review template.? They’ll check the checkboxes, fill out the text for the questions, and generate adjustments to the code where needed.? For a while, anyway.

But where you’d eventually expect the efficiency of these reviews to improve, the opposite happens.? The document grows. Code reviews get longer and more mind-numbing, and people start to hate them.? Then, they start to?avoid them altogether, when possible.? The group’s collective dissatisfaction eventually leads to an overhaul of the process.

And the code review template sits there on SharePoint, untouched, like a digital fossil.

The Drudgery of a Code Review Template

Okay, so what happened?? What’s the problem, exactly?

To understand the issue, let’s break the existence of the code review template into two conceptual phases:

• Conception, where team members decide what should be true of the codebase.
• Execution, where team members enforce the template at code review time.

When you gather for the conception portion, you’re engaging in a very “yes-and” kind of activity.? This isn’t to say that team members won’t ever argue for the exclusion of an idea; rather, in general, it’s easier to err on the side of over-inclusion because you’re not currently feeling the friction of too long a list.? Think of shopping for a new car.? Just about every feature, bell, and whistle seems like a good idea…at least until you see what it does the price.

Execution time is where you get that sticker shock.? “Wow, it sure does take a long time to go over all of this stuff,” you might hear initially.? But you grin and bear it since you figure it’ll get better with time and that you’re catching important potential issues.? And you probably?are catching important issues from time to time.

But you’re also almost certainly not doing something else.? You’re almost certainly not evaluating whether each item in your template catches issues frequently enough to be worth the time it consumes.

And, over time, the satisfying feeling of creating the template fades, leaving only the rote drudgery of execution.? This drudgery persists until the group throws the baby out with the bathwater.

What’s the Alternative?

At this point, you’re probably thinking that I’ve already mentioned the fix.? I mentioned evaluating each item in the code review template regularly to see if it’s pulling its weight.? So that’s the fix, right?? Why don’t I just recommend that, instead of claiming that you don’t need the code review template at all?

Ah, but it’s a little more complicated than that.

Let’s say you take this approach and routinely audit the code review template, culling outdated concerns, adding new ones, and revising existing ones.? Let’s also assume that you have enough time to do this meta-activity and get everyone’s buy-in (which is far from a given).? How, exactly, do you evaluate the value of a checklist item or template question?? Here are the factors that come into play.

• The magnitude/importance of issues it prevents.
• The frequency with which team members actually make the mistake in question.
• The cost of checking and fixing.

Here’s the problem with a Word document containing a code review checklist.? Each and every item on it has non-trivial cost for checking and fixing, which means that you’ll get negative return on items in the template that either aren’t that important or don’t come up very often.? And the tendency of these code review templates to grow with time exacerbates the problem.

For this to be worthwhile, you need to get the cost of checking and fixing to zero.? And to do that, you need automation, not a Word document.

Automation as a Template Replacement

Consider a few things that you’ll typically see in some code review template’s list of checkboxes.

• Avoid compiler warnings.
• New code should be covered by unit tests.
• Don’t copy and paste code.

You can automate checks for each of these and incorporate them into the build.? Heck, the first one is as simple as flipping a setting, in many development environments.? Developers wouldn’t be able to compile without complying with this checklist item.? If a violation stops people from compiling, I promise you that you don’t need to worry about it at code review time.

When you automate these things instead of putting them into a Word document to guide human checking, you reduce the cost of checking and fixing to zero and near zero, respectively.? But you also do something far more important.? You free the developers to think of bigger-picture design issues while coding.

Think of it this way.? When you write code, you can only keep so many things in your head at once.? Most code review checklists have?far too many items for developers to remember them all.? So they don’t bother trying and they wait for feedback at code review time.? But if you automate most of the feedback, they’ll learn in real time, correct, and internalize the lessons.? They then?can keep some items in mind as they go — more philosophical, big-picture ones like “methods should have only one responsibility.”

The Approach You Should Take

If you found this post by searching for code review templates, then stop your search and do something different.? If you’re currently in a shop where you have a clipboard-style checklist, then revise your approach.? Here’s what I’d recommend instead.

First, get some tooling and automation in place.? This includes automated code review tools, static analyzers, code formatting tools, build automation, and even custom code that you write.? Identify everything in a prospective checklist that you can automate, and then automate it.? As you automate each one, delete it from your checklist (or prospective checklist).

Then, look at the items that remain.? The ones you can’t automate.? These will, I assure you, be more philosophical.? Does your code follow the SOLID principles?? Do you conform with the principle of least astonishment?? Are you separating your concerns and creating good abstractions?

Notice that all of these require human conversations and the value judgments of experienced software developers.??That is what your code review?should be — a discussion.? And you don’t need a code review template to make that happen.? You just need to automate the simple stuff and have a healthy group consensus on what it means, philosophically, to write good code.

Learn more how CodeIt.Right can help you automate code reviews and improve the quality of your code.

About the author

Erik Dietrich

Website

I am Erik Dietrich, founder of DaedTech LLC, programmer, architect, IT management consultant, author, and technologist.

This author does not have any more posts.