Code Usability

Most of the time, when people talk about usability, they’re talking about usability of a user interface, about how to design the user interface to make it user-friendly. However, as the name implies, it applies to anything that can be used and doesn’t need to be something that can be seen (more about that in a future post). Today, I’ll talk about Code Usability, a concept that many programmers probably use, but don’t have a name for.

More specifically, I’ll divide the concept of code usability in two.

Readability and Maintainability

The first step to having good usable code is to have code that is easy to understand. Your coworkers and yourself from the future should be able to dive in the code and understand what it’s doing. They should also be able to modify it without the fear of breaking everything. Joel Spolsky calls it hallway usability testing (see step 12 of The Joel Test).

There are plenty of articles about improving code readability and maintainability so I won’t go into too much detail here. The most important things to think about when writing code is to make it as self-explanatory as possible (appropriate names for variables, classes, methods, …) and add comments that explain why, not how.

Comments are important and using them correctly can be difficult. And the more complicated the code is, the more complicated writing the comment can be. As non-commenting programmers like to say:

If it was hard to write, it should be hard to understand.

Yes, but you should make it as easy as possible to understand, because you might be the one that will have to fix it in a year.

Usability

Once your code is readable and maintainable, how easy is it to use your creation? Do I have to jump through loops to make things work? Do I have to check how it was coded to understand what it’s supposed to do?

Code usability is as important as readability and maintainability. Code should be easy to use and not just for you.

This post about code usability (the only one I found talking about this concept) sums it up nicely:

The user of a component must feel confident when using it. The interface of a component must be clear and coherent; it should be as self-explanatory as possible; and it should be simple.

The first step is to make sure to give the appropriate name to the classes, the methods, properties, etc. Don’t make the user of your component have to figure out how to do something, he should find it intuitively. The same principles of usability apply to code usability: make it easy to use.

1 comment
Louis Côté on April 29, 2009

Excellent article, and true words of wisdom! I totally agree with you on intention-driven as opposed to implementation-driven commenting : the ealier enables someone else (or its functional equivalent : the same person a few months from now…) to validate what the code is meant to do, while the latter does not.