The Rules of Programming

Rule 18. Let Your Code Tell Its Own Story

There’s a lot of focus in this book about making your code easier to read, whether it’s by being careful about hiding the behavior of your code behind extra abstractions, choosing good names for things, or choosing the simplest workable approach to a problem. Writing code that’s easy to read makes everything else go more smoothly, since we all spend a lot more time reading and debugging code than we spent writing it in the first place. When you’re debugging a bit of code, it’s much easier to figure out what’s going wrong when you have a quick way to understand what it’s trying to accomplish.

That’s especially true for a project you’re working on as part of a team, but it’s even true for a solo project. If you’ve got a nontrivial solo project going, one that you’re spending weeks or months or even years on, you’ll end up needing to refamiliarize yourself with code you wrote long before. Whatever thoughts you had in your head when you wrote that code will have faded away; all that’s left will be the code itself. At this point, you’re in pretty much the same place as a coworker on a group project: you need to sort out what the code is doing (or trying to do) by reading it.

Here’s another way of thinking about this—Future You is a stranger.

Unless your project will get wrapped up and thrown away in a day or two, expect to come back to your code as a stranger. Do Future You a favor and make it easy to read.

Imagine walking someone through some ...