Code review is one of the most powerful tools we, developers, have in our toolkit. There are plenty of resources providing information on the value code review can add to any development team. However, most of the resources I have read, describe how to use code reviews as a tool to find bugs, or architectural issues that are hard to find in an automated way.

It’s also a known argument that code is read much more often than it is written and that it’s harder to read code than to write it, so, our common sense should indicate that writing clear and obvious code can provide a lot of value to our readers, our fellow programmers.

Usability Testing

I’ve recently read the book ”Don’t Make Me Think”, by Steve Krug, which is considered by many as the bible for usability on the web (and if you haven’t read it yet, you should. It’s a great read). The key concept could be best described in Steve’s own words:

It means that as far as is humanly possible, when I look at a Web page it should be self-evident. Obvious. Self-explanatory. I should be able to “get it”—what it is and how to use it—without expending any effort thinking about it.

And while I was reading this, I was thinking, why is code any different? Why should we spend all this time reading legacy code, trying to figure it out, when the code author could write it in a clearer way, easier to understand.

Consider the challenges in reading someone else’s code:

• Did they use code conventions you are familiar with?
• Did they write clear interfaces?
• Did they use well known design patterns?
• Did they name variables in a clear, non-ambiguous way?
• Is the code explicit rather than implicit?
• Is the implementation easy to explain? If not, why not?
• Is it complicated? If it is, does it have to be?

Point is, there’s a lot into reading code, and it gets even more complex when style and requirements change over time.

Then it accrued to me that there is nothing that holds us from testing the usability of our code. A proposal on how this process could work:

Code Usability Testing

As a part of code review:

• Find two or three developers in your company, some that are unfamiliar with your code. Better if you can find new developers, or developers from a different team than yours.
• Give them a task. Ask them to implement something using your code, or to tweak your code in some way
• Ask them to share their process of thoughts with you, as they are trying to accomplish the task
• Refuse to provide any help. Let them figure it out
• Observe their work, and keep notes

This practice should not take a lot of time. It should not take more than 30 minutes for each engineer participating, depending on the size of your commit. Then it will take you up to 30 more minutes to analyze the results. The obvious problems will be very easy to identify, and the rest could be ignored, until the next review. I’m sure these extra (tops) 2 hours will provide tons of useful information on how to make your code simpler clearer and overhaul better.

Just keep in mind to stay open and don’t take it personally. We have to always keep in mind that what’s obvious to us may not be obvious to everybody.

Usability testing is probably the easiest way to tell us if we’re doing it right clear, and what should be tuned.