Translations: Korean (한국어).
I launched GoatCounter: privacy-aware web statistics.
You can now support my work.

What does it mean for a framework, library, tool to be “easy”? There are many possible definitions one could use, but my definition is usually that it’s easy to debug. I often see people advertise a particular program, framework, library, file format, or something else as easy because “look with how little effort I can do task X, this is so easy!” That’s great, but an incomplete picture.

Code is written only once, but will almost always go through several debugging cycles. With debugging cycle I don’t mean “there is a bug in the code you need to fix”, but rather “I need to look at this code to fix the bug”. To debug code, you need to understand it, so “easy to debug” by extension means “easy to understand”.

Abstractions to make something easier to do often come at the cost of making things harder to understand. Sometimes this is a good tradeoff, but often it’s not. In general I will happily spend more effort writing something now if that makes things easier to understand and debug later on. It will often be a net time-saver.

Simplicity isn’t the only thing that makes programs easier to debug, but it is the most important. Good documentation helps too, but unfortunately good documentation is uncommon (quality is not measured by word count!)

The effects of this are real. Programs that are hard to debug will have more bugs simply because it’s so much harder and more time-consuming to fix bugs, even if the initial bug count would be exactly the same as a program that is easy to debug.

In a company setting, it’s often not considered good Return Of Investment to spend time on hard-to-fix bugs. In an open source setting, people will contribute less (most projects have one or handful of regular maintainers, but a long tail of hundreds or even thousands of contributors who submitted just one or a few patches).


This is not exactly a novel insight; from the 1974 The Elements of Programming Style by Brian W. Kernighan and P. J. Plauger:

Everyone knows that debugging is twice as hard as writing a program in the first place. So if you’re as clever as you can be when you write it, how will you ever debug it?

A lot of stuff I see seems to be written “as clever as can be” and is consequently hard to debug. I’ll list a few examples of this pattern below. It’s not my intention to argue that any of these things are bad per se, I just want to highlight some trade-offs in “easy to use” vs. “easy to debug”.


I launched GoatCounter: privacy-aware web statistics.
You can now support my work.