For all the software guys and gals out there, earlier this week, I saw a somewhat funny, somewhat cranky, and mostly insightful article by Jack Ganssle, which appeared on embedded.com. His topic? How we name things – functions, variables, parameters, macros, identifiers – when we code.
Now coders tend, by their very nature, to be logical and to think things through. So it’s not as if no thought is given to naming. It’s just that, as Jack points out, what might seem logical to us may not be so logical to someone picking up the code and trying to figure out what’s going on when, years later, they inherit it.
Jack starts out with a critique of the names for the logging levels for the Linux printk function, starting with KERN_EMERG.
“What, exactly, does EMERG mean? Emergency? Emerging? Emergent? The latter sounds like part of the title of a horror movie.”
Okay, this is funny, but I think that most of us would see this and think “emergency,” which is, in fact, what it stands for. Still, the point it well taken.
He’s not arguing, by the way, for long names that spell everything out in hopes that this approach will “yield self-documenting code (which isn’t true).”
But all this abbreviating we do doesn’t help much either, since it can cause confusion. As in “emergency” vs. “emerging.”
As he says:
“The code has to do two things: work, and express its intent to a future version of yourself or to some poor slob faced with maintaining it all years from now after you’re long gone. If it fails to do either, it’s junk.”
Let’s all keep in mind that the naming goal should always be clarity, and sometimes it’s best to add a few characters to help eliminate confusion.
The article is definitely worth a look, as are the comments.
Anyway, I was discussing this topic with a friend, and she told me about a couple of mainframe software coders she worked with back in the day. One would write error messages using non-English words, and/or throw in literary references. Her favorite was the message that said “something gang agley here,” which combined a foreign language that few were familiar with (Scots) and a nod to Scots poet Robert Burns, who wrote “the best laid plans of mice and men gang aft agley,” which means often go awry. A couple of things worth noting here: error messages really aren’t the place to show off your obscure knowledge, and, two, an error message that says ‘something’s gone wrong’ isn’t exactly being informative, now is it?
The other guy she mentioned also got creative with error messages, but he went in for insults. As in “if you’re getting this error message, you’ve done something really stupid.” Just what one of your end-users or customers wants to see!
So, if you’d like to do some thinking about how you go about naming, take a look at Jack’s column. And when you’re writing error messages, keep in mind that the purpose is to inform, not confuse or insult.