Who Are You Writing To Anyway?

I’ve written about this before. When you’re writing code, who are you talking to? The simplest answer is that you’re writing to the computer. To the assembler, compiler, or interpreter, depending on the language you’re using. And at some level, that that’s true.

However, there’s a lot more to it than that. As the great philosopher and programmer, Anonymous, once said

A programmer does not primarily write code; rather, he primarily writes to another programmer about his problem solution. The understanding of this fact is the final step in his maturation as technician.

In fact, we generally, have at least three audiences. Of course, the assembler/compiler/interpreter is one of them. The second audience is the folks that review the code after¹ it’s written or pair with you while it’s being written. The third, and most often forgotten, is the maintainer.

The thing is, your compiler (or assembler or interpreter) doesn’t understand what you wrote. Instead, it follows a very strict set of rules to translate what you wrote into a series of 1’s and 0’s that the computer can execute. (NB: The computer doesn’t understand it either. Ij just knows how to execute it). It’s completely on you, the developer, to ensure that what you write does what you want. The compiler doesn’t care. As long as you follow it’s grammar rules it will come up with something for the computer to do. If it does what you want and expect it to do, great.

If not, someone else is going to need to read the code. And that person is going to need to understand it. That person might be you 10 minutes after you wrote it, when you _probably remember what you meant. In that case it’s relatively easy to figure out where what you wrote and what you meant aren’t the same. Another very common case is you, 6 months or 6 years after you stopped thinking about that bit of code.

In that case, you look at in confusion, wonder what idiot came up with it, check git blame, and silently yell at your former self. Then you piece together what you meant, dust of the old constraints you mostly forgot about, and then move forward.

Worst case is that when you check git blame you find that the most recent changes where 5 years ago, and all of the people who ever touched the code no longer work there. You’re on your own. You need to figure out what the code is actually doing, why it does it that way, and what odd constraint, that you don’t know about yet, has changed.

And that’s the person you’re writing the code to. The maintainer. The person who has to live with the code long after the thrill is gone. As John Woods said,

Always code as if the person who ends up maintaining your code is a violent psychopath who knows where you live.

I usually maintain my own code, so the as-if is true.

Or maybe you prefer Martin Fowler’s way of saying it.

Any fool can write code that a computer can understand. Good programmers write code that humans can understand.

So write your code in a simple, straightforward manner. Make it understandable. Reduce cognitive load. Don’t require that the reader carry a lot of context. Don’t be clever. Don’t be a cowboy.

Because, if we’re doing it correctly, we ALL read way more code than we write.