Don’t Be Mislead: How to Interpret a Code Review

By Dave Hecker on
Managing Teams

At some point, every CTO or technical lead will need to make a judgment call about a developer who isn’t performing well. A code review is sometimes used to assess the “quality” (note the quotes) of developers’ output, but interpreting the results of a code review is not as easy as it might seem.

The Context Sets the Tone for a Code Review

code-300x225Code reviews are only useful if the context of the development is understood, otherwise, they’re almost useless. When a code review comes your way, be sure to consider what was going on when the developer wrote the code. Consider how useful a code review would be in these two circumstances:

1. A team is given a set of features to implement, and due to an overestimation of the scope, a generous timeframe to implement it. Their questions get answered promptly, the QA department does a great job finding bugs, and the project manager is quick to provide refinement direction and demo for management at the right time. During the bug-fixing phase, the developers make an internal decision to add a few hours here and there to refactor a few parts of the code that have become messy due to changing specs, and in the end, they are pretty satisfied with the result. Weeks later, a code review reports that their code was well organized and of high quality.

or

2. That very same team is given 2 weeks to add a feature to a complex application, a late requirement to meet a conference date. The team balks, but they manage to squeak out some code and aside from a few minor bugs, the feature works. The team is proud to have met the deadline, they are great coders that know how to cut corners and crank out a feature when asked to do so. Weeks later, a code review reveals “sloppy code” in that part of the application, and this information is related to client-side management, who assumes that the team isn’t doing a good job.

In either scenario, a code review or a code review tool can be misleading without the background info. A great team should be able to crank out some sloppy code when needed, or write elegant code when given loads of time.

The key here: Always know what your developers were asked to do before you evaluate how well they did it.

How Reliable Are Your Narrators?

To get a handle on the context – beyond the documents like specs and project plans you’ll review – I’d encourage you to simply ask the developer to discuss their thoughts on the code from their perspective. Some pointed questions may be called for – checking the developer’s alignment with project documents, etc – but open-ended questions work wonders here.

The developer’s manager will also provide some good perspective, but be on the alert: Managers often lean on code reviews and pronounce them “objective.” That’s because code reviews are a perfect (and frequently used) tool for all sorts of organizational maneuvering and managerial actions (including CYA). If a manager wants to put some heat on – or get rid of – a developer, a code review is a great way to do it. A manager will know exactly when to spring a code review on a developer, and how it can be done that will do the absolute least damage – or the most if that’s their intention.

The key here: Consider politics or personal agendas that might be involved when a code review comes across your desk.

The Slippery Slope: Definitions and Standards

gavel-300x200Another sand trap is having too much focus on standards and best practices in the code. Obviously, standards and best practices are an important part of every code review, but too much emphasis on standards can be misleading and it’s rare that any developer has time or energy to be 100% compliant with standards. Ironically, if every line of code that was written was perfect in regard to coding standards, management would probably be complaining that things are taking too long.

And what is “quality”, anyways? There are so many code standards and best practices to choose from, this becomes a highly subjective subject and developers are frequently left at the mercy of the reviewer’s whim. At the very least, make sure that every developer has a clear understanding of what best practices the has team adopted for this project, and to what degree those best practices can be violated given the deadline, resources, and technical difficulty of the work.

A good way to look at this is the trusty 90/10 rule – if the code is 90% standards-compliant, that might be enough so long as the remaining 10% is still decent quality. Even the best programmers may leave behind a few poorly named variables or subroutines that would take too long to fix unless some refactoring time is granted.   I’m certainly not saying that you should overlook a spaghetti-mess of code – that’s just not acceptable. All the code must be of reasonable quality. But, it’s not always practical (or advisable) to expect 100% perfect standards-compliant code every time and in many cases that last 10% can eat up a lot of time and energy.

The key here: Having definitions and standards in place before a project starts, and a clear understanding of the expectations of the developers. Be careful not to focus on standards beyond the point of diminishing return.

Make the Code Review Meaningful

The final reason that code reviews are often unreliable is that most code reviews are mediocre, and great code reviews are rare. Why? Code reviews tend to be conducted in boring, tedious, or thankless ways, and are much less fun that just about anything else a tech manager could be doing. Most code reviews are performed quickly or lazily, with reviewers finding a few things to criticize but otherwise giving the code a pass without really digging deeply.

An easy way to make things less tedious for the reviewer is to have them chat with the developer rather than just reviewing the code. This allows the reviewer to learn about non-code circumstances that will make the review more useful – such as any challenges that were overcome when the code was written and any special issues or management constraints that made things extra tough. A more conversational, interpersonal approach will also make the process less daunting for the developer, who will now have a voice in the final result.

The key here: Make your code review process more engaging and enjoyable. Developers themselves may have great suggestions as to how to accomplish that.

How To Make Code Reviews Work For You

A code review that is well written, objective, and takes a deep look at the quality of developers’ code can be incredibly useful.  Here are some tips on how to make your code reviews count:

  1. Make a situation/context analysis of the report. Every code review should start with a summary including the experience of the developer(s), the amount of time/deadline pressure they are under, and the state of the code that they are working on, based on the agreed definitions and standards. Seek to capture a few paragraphs about what was happening when that code was written.
  2. Let the developer respond to the report before you ever see it. Every developer deserves a chance to see and respond to a code review before it goes up to management. This helps to ensure that any challenges that the developer was facing are documented in the report, and it also keeps managers honest by reducing the chance for “gotcha” style code reviews. It also makes developers feel like they are being respected rather than spied upon.
  3. Make sure the reviewer is motivated and qualified. This is a tough one. Only a good developer can recognize good code, so a good code review can only be achieved assigning one of your best developer to a boring code review effort. Try to bring the reviewer into the process by allowing them some mentoring time with the reviewee, or at least giving them some appreciation for doing such tedious work.
  4. Try to remove politics and personal agendas from the process. This one isn’t easy either, but it can be done. Think hard about who will be doing the reviews, and how that person might like to steer the results. If you aren’t 100% comfortable with that stance for internal team members, consider using an outside consultant to do the reviews.
  5. Collect both quantitative and insightful qualitative data. It’s easy for the reviewer to look at things like syntax, organization, variable names, commenting, etc. Those are the low-hanging fruit that makes up a lazy code review. Encourage the reviewers to explore things like the way that the code is organized, the logic and data structures that are used,  and the style of problem-solving that the developer employed. These broader observations can be much more useful than the little stuff, like variable naming.

The above tips should help you to have a better understanding of the next code review you receive, and how to improve your organization’s code-review process. Please let us know in the comments if you have any questions or interesting tips.

Dave Hecker

Co-Founder at SourceSeek at SourceSeek
Dave is a seasoned technology executive focused software delivery, quality, process, and helping clients succeed at international software outsourcing.

Latest posts by Dave Hecker (see all)