Lessons in Good Naming through Absurdity
There’s something I’ve found myself stressing a lot lately to people on my team. It’s a thing that probably seems to most like nitpicking, but I think is one of the most, if not the most, under-stressed aspects of programming. I’m talking about picking good names for things.
I’ve seen that people often give methods, variables and classes abbreviated names. This has roots in times where saving characters actually mattered. Methods in C had names like strcat (concatenate a string), and that seems to have carried forward to modern languages with modern resource situations. The reader of the method is left to try to piece together what the abbreviation means, like the recipient of a text message from someone who thinks that teenager text-speak is cute.
There are other naming issues that occur as well. Ambiguity is a common one, where methods have names like “OnClick” or even “DoStuff.” You’ll also have methods that are occasionally misleading — a method called “ReadRecords” that reads in some records and then actually updates them as well. Giving this a simple name like “ReadAndUpdateRecords” would take care of this, but people don’t do it. There are other examples as well.
All of this probably seems like nitpicking, as I said a moment ago, but I contend that it isn’t. Code is read way, way more often than it is written/modified, and it’s usually read by people who don’t really understand what was going through the coder’s mind at the time of writing. (This can even include the original coder, revisiting his own code weeks or months later.) Anything that furthers understanding becomes important for saving minutes or even hours spent trying to understand. Methods with names that accurately advertise what they do save the maintenance programmer from needing to examine the implementation to see how it works. When there is a standard like this through the entirety of the code base, the amount of time saved by not having to study implementations is huge.
Toward the end of achieving this goal, one idea I had was a “naming” audit. This activity would consist of the team assembling for an hour or so, perhaps over pizza one lunch or evening, and going through the code base looking at all of the names of methods, variables, and classes. Any names that weren’t accurate or sufficiently descriptive would be changed by the group to something that was clear to all. I think the ROI on this approach would be surprisingly high.
But if you can’t do that, maybe a more distributed approach would work — one that combines the best elements of shaming and good-natured ribbing, like having the person who breaks the build buy lunch. So maybe any time you encounter a poorly named method in the code, you rename it to something ridiculous to underscore the naming problem that preceded it. You bring this to the method author’s attention and demand a better name. Imagine seeing your methods renamed to things like:
- Blammo(int x)
- Beat(int deadHorse)
- Onoes(string z)
I’m not entirely sure if I’m serious about this or not, but it would make for an interesting experiment. Absurd names kind of underscores the “dude, what is this supposed to mean” point that I’m making, and it’s a strategy other than endless nagging, which isn’t really my style. I’m not sure if I’ll try this out, but please feel free to do so yourself and, if you do, let me know how it goes.
I’m interested in experiences around pushing name auditing policy in action on real live project with real (live :)) devs. And I wouldn’t like to hear about some document somewhere that states what is good naming.
Yeah, I don’t think I’d really be looking for some sort of bloated standards document — that’s depressing. It’s really the audit of “does this do what it says” and “is this clear to everyone.” If I start doing the name audits, I’ll follow up with my experience.
“…and it’s usually read by people who don’t really understand what was going through the coder’s mind at the time of writing. (This can even include the original coder, revisiting his own code weeks or months later.) ”
I call this WITHWITH – “What In The Hell Was I Thinking Here?”
I think that looking at my own code and names is what gave rise to this line of thinking as much as anything. So many times where I thought, “why didn’t I just spend an extra 5 or 10 seconds actually describing what I meant with this variable name?”
Absolutely one of the most important aspects of programming, and so worth it when you come up with good names. Also reminds me of:
There are only two hard things in Computer Science: cache invalidation and naming things.
— Phil Karlton
I wasn’t familiar with that quote, but it’s a great one. I’ll definitely remember it now.
It’s also worth remembering the variation of this quote by Martin Fowler: http://martinfowler.com/bliki/TwoHardThings.html
I remember off by one errors from my early years of programming. These days, though, with a lot of “foreach” and using TDD, I don’t run into this a lot.