entropia

I’ve had this post on the back-burner for a few months. It wasn’t until I read Only Code Has Value? that I decided to finish it.

If you have well-written code, you can easily understand what the code is doing. However, even the best-written code can’t reveal why it is doing it. That’s because the question of “why” is not centered on the code itself, but on the context it operates in and the design decisions made during the development of the system.

I don’t think I can put it any better than that: there’s no way for code to explain the Why. And without the Why, you are powerless.

Our only hope, our only peace is to understand it, to understand the `why.’ ` Why’ is what separates us from them, you from me. `Why’ is the only real social power, without it you are powerless.

As recently as a couple years ago, I didn’t care much about what code looks like. As long as your program does what it’s supposed to, it’s all good. Sure, it’s nice when other people can easily understand how it works, but that’s not as important. Besides, if they’re to understand the Why, they’ll need some form of documentation anyway. You might as well just put the How in there too.

More recently I’ve been reading blogs and books that promote readable, extensible code. One of the quotes that comes up again and again is from The Structure and Interpretation of Computer Programs:

Programs must be written for people to read, and only incidentally for machines to execute.

That’s a fine theory, and definitely something that we should strive for in practice. But when was the last time you came across a non-trivial piece of code that you immediately understood? Even the most well-written code takes time to read - to understand the How. It would help if you already had the power of knowing the Why.

Maybe we should spend a little less time making sure our code is readable, and start spending some time on the documentation.