Put it back where you first looked for it

If you are looking for something in your house, and you finally find it, when you’re done with it, don’t put it back where you found it. Put it back where you first looked for it.

— https://kk.org/thetechnium/68-bits-of-unsolicited-advice/

How do you name variables and functions? How do you make APIs that are easy to use? How do you organize modules and components? How do you structure assets, styles, and markup?

To all of these, there is one simple answer:

• Do it
• At some point you’ll end up looking for stuff
• If it takes more than one step, change it so it only takes one step
• Repeat

When you’re first creating an API you imagine what it would be like to use it. Most likely you’ll get some of it wrong. Do it anyway. Later on, when you’re using that API, you start to realize that things are not where they’re supposed to be, names don’t match what they’re doing, there’s too much overhead between what you’re trying to do, and how easy it is to accomplish.

That’s your cue to go and fix all these mismatches. Move things to where you expect them to be, rename to what you were first looking for, make it easier to use.

When I talk about it, I call it “SEO for code”. Say you start out by writing a method that will retrieve all the latests posts, so getLatestPosts sounds about right.

Later on, when you’re looking it up, you end up looking for “list” and “recent”. Those are your search terms, but your content (code, API docs, etc) doesn’t have good SEO, and you fail to find it.

Search long enough and you will find it, but what if instead, you rename it to match your searched keywords? If this was a web page and you wanted people to find it, you’ll be changing to match what they search for. Rename to listRecentPosts. Done.

If you want to know whether you’re making progress, a good metrics, is WTF/minutes. Whenever something isn’t where you’re looking for it, doesn’t do what it says, or isn’t obvious at first sight, that’s a WTF.

Higher code quality has low WTF/minute. You always intuitive know how to get that metric down, it surprising so many people don’t do that.

The same things applies for organizing files: does it go in the src, models, or lib directory? For CSS styles: should I call this button, signup, or cta?

More important is how this plays in the long run. Sometimes you choose wrong, and sometimes things change over time, and your initial choice is no longer the best. This is where you get to decide.

If you put up with your old choices, you never get better at naming and organizing. If you make a practice out of spotting and correcting mismatches, with time you get better at organizing from the get go.

That is all of it. You only need this one rule and keep practicing:

Put it back where you first looked for it.