Published
Put it back where you first looked for it
A blog post about naming and organizing things.
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.