Names Are Important

Most of the engineers I work with know that I’m obsessed with names.  Not names of people, mind you.  Strangely, I can barely remember those, which can be pretty darn embarrassing as a consultant and instructor.   No, the names I’m obsessed with are the names of software things:  local variables, structure fields, and names of functions.  I agonize over them.  I change them about a million times.  I try to choose a name that’s just right.  As the French would say le mot juste.  I pick one.  I go home for the night.  I come back the next morning and change it again.

The reason I think that names of things are important in programming is that I believe the name of something in a program should clearly convey to the reader information about its function and use.  I don’t really care if a loop iterator is named i or n.  But I care a lot about the names of useful local variables and structure fields.  Besides conveying information about their meaning, I also like the names of my variables to “read” nicely when they appear in my code logic.  So, for example, if I need to track the whether a given device is active, I’d probably name the field of my Device Context something like “DeviceIsActive” because this lets the code read almost in English:

If (devContext->DeviceIsActive) {

//
// Do something when device is active
//
…
}

And it should go without saying that the same object should have the same variable name in every function.  Gad!  It’s scary how often I see this little detail missing in code I review from clients.  Consistent naming is right next to clear naming in my book as an important attribute.  So, if the local variable that holds a pointer to your Device Context is devContext in your EvtDriverDeviceAdd function, then all the local variables in your whole driver that hold the pointer to your Device Context should be devContext.  Or, of course, DevContext if the variable is passed as a formal parameter to a function.

While I care a lot about the names of local variables and structure fields, the names I agonize over most are the names of functions.  Some of my colleagues at Microsoft could attest to this.  On multiple occasions I’ve managed to call meetings with various devs (some of them pretty senior people) for the sole purpose of pissing them off by arguing over the name of some driver support function.  I complain”: “Cmon… You’re not *really* going to leave the name of this function as IoXyzAbc are you??  Who named this, anyways?!”  Most of the time, the argument I’ve gotten back is “OK, the original name isn’t great, but it just doesn’t matter that much.  Pick a name.  We’ll tell you if we like it.  But, mostly, please just shut up so we can end this meeting because we have real work to do.”

This attitude makes me absolutely nuts, because I think function names really matter.  For example, in my driver I care a great deal if the name of a function is MyDrvInitialize or MyDrvCreateControlDevice.  The former tells you absolutely nothing about the function beyond when it’s likely to be invoked.  The latter, on the other hand, tells you what the function is intended to accomplish.  So, why would the name of a function that thousands of people will have to call be any less important?  Let’s spend some time, think about it, and discuss the alternatives.  I wish I could give you some examples, but that wouldn’t really be appropriate.  It is worthwhile noting that in these meetings I’ve never succeeded in getting my first choice of name.  But I’ve always managed to convince people that to at least change the name to something palatable.

One thing that definitely enables my name obsession, at least within code for projects I’m personally responsible for, is the ease with which I can rename things from within Visual Studio. I use Visual Assist X (they give Microsoft MVPs like me a free copy, thank you Whole Tomato Software!) which has the world’s easiest “refactor/rename” feature.  It looks like this:

 

One click, and the rename is accomplished!  Sometimes, it’s good to be enabled.  Of course, the other devs working on the project regularly curse me: “My code won’t compile.  Again.  Ahhh… wasn’t this structure originally named FRED_CMD_DATA?  And now, it’s what?  FRED_COMMAND_REQUEST_BLOCK?  Ugh!”

Sorry guys.  Sometimes I just can’t help myself.