Friday, June 07, 2013

Is It Easier To Write Code Than To Read It?

The Premise

A recent Programmers Stack Exchange post reminded me of a seemingly widespread belief among programmers - writing code is easier than reading code. In his post, "Things You Should Never Do, Part I", about not writing software from scratch, Joel Spolsky writes, "It’s harder to read code than to write it". Most other posts I have found on this topic seem to reference Joel's article. They nod along in agreement as if to say that, once revealed, this premise is gospel truth and cannot be denied.

Horror Stories

Any programmer who's been around the block a few times can remember some godawful snippet of source code that warped their minds and nearly broke their will. Foreign (AKA not mine) source code may be difficult to understand for a variety of reasons. It may be oddly formatted, use poorly named variables and functions, have confusing organization, or seriously lack comments. Other than code full of "clever" tricks (why multiply by 8 when you can just use the bit shift operator?), I believe the most difficult code to read is simply at a level of complexity beyond the expectations of the reader.

Since everyone seems to recall a story about an undecipherable code base from their past, it becomes easy to latch onto Joel's premise. We know that if we aren't careful about our code choices, it can grow into an unholy mess full of badly-named functions full of side effects that run over multiple screens. It's easy to get code into this state and it's difficult to deal with maintenance once the damage has been inflicted. In this sense, Joel's premise is correct.

Defining Difficulty

If we ignore "bad" code and focus on "good" code, I believe that the picture changes. Writing good code is hard. Choosing meaningful and descriptive names for variables and functions is difficult. Structuring and documenting code so it's easy to understand and modify is a constant struggle. Self-documenting code contains all kinds of clues about the purpose of each component and demonstrates how each piece interacts with the other.

I think that part of the problem comes with the vague way we define difficulty. What makes one task hard and one task easy? There are several ways to measure difficulty. Some are more meaningful than others.

I think some of us choose to define difficulty based on our interest in performing a task. Clearly, watching TV is easier than washing the dishes. This measurement breaks down when a task is both challenging and interesting. I'd much rather climb a rugged mountain trail than take out the garbage, but scaling the mountain provides a much bigger challenge than dragging the trash to the corner. Programmers love writing code because of the intellectual challenge and the joy of creating something from nothing. Understanding the work of another coder does not generally hold the same appeal.

When it comes to business, a much better way to measure the difficulty of a task is in the cost in resources. In this case, we're talking about the time and effort of a programmer. It may not be fantastically interesting to decipher someone else's code, but given a well-written code base, understanding comes with perseverance. Rewriting the same piece of code (larger than a few hundred lines) to the same level of quality will require an order of magnitude in extra time.


Here's the bad news: every field has unpleasant tasks. As a programmer, I prefer writing new code over maintaining old code. When someone proposes an unpleasant task, people tend to come up with all kinds of excuses to avoid it. This is as true for programmers as for anyone else. The excuses pile up until we talk our way out of doing the unpleasant task.

Unfortunately, as professional software developers, we're not being paid for pleasant. We're being paid for results. Great developers recognize this and exercise discipline. They buckle down and read the code carefully. They are able to understand it much more quickly than it could be rewritten. Once they understand the code, they make their changes and move on.

The good news is that if you follow this approach, you'll get things done quickly and be able to move on to new projects. Reading good code instead of rewriting it will result in a higher level of productivity. Your boss may just take notice and reward you for your efforts.


Joshua Ganes