Adam @ Bitscribe

Programmers typically don’t worry much about naming within the code.  After all, the user isn’t going to see what your variable are named.  You know what they do; so what if you’ve got variables named a, a2, and _a?

The beginning of wisdom is to call things by their right names.  Giving a proper name to a module, class, method, or variable is a sign that you truly understand what it’s supposed to do.  In fact, the very act of searching for a name can often help you figure this out.  It’s a process of determining the component’s true identity.

If you can’t think of a good name for the component, there’s a good chance you don’t really understand what it should be doing.  Time to rethink your design.

There’s also the perception that the internal names for things need not match their external names.  The problem with this is that you impair communication between users, designers, and developers.  Bug reports from users will come in with their external names.  There’s a cost in mapping one name to another every time you get a bug report, and if you’re writing any kind of serious applications then you’ll have an awful lot of bug reports.  Changing the name of the component need only be done once, but you’ll have to deal with the mapping every time.

Then there’s the matter of new developers coming onto a project.  The more obvious and concrete your component names are, the easier it will be for them to get up to speed.  Let’s say you’re exploring an unfamiliar codebase that you know is an e-commerce suite of some sort.  You come across a module named “Process.”  Quick, what do you think it does?  One guess is as good as another.  On the other hand, if the module were named “Checkout”, you’d have a pretty good idea what it does before even opening up the source file.

Good names should be short and distinctive.  Many programmer, once they get past the a, a2, _a approach to naming go the other extreme and start naming variables number_of_orders and products_to_be_saved_to_disk.  A name that is too long will clutter up the code and make it hard to read, which is only slightly better than being short and cryptic.  num_orders and queued_products are about the right length.

Poor names are often not the result of a poor initial name choice, but instead a result of the natural organic change of the code over time.  The module may evolve to take on a different role, or it might stay static and the rest of the application changes around it.  Either way, the result is to make a once-good name obsolete.

As soon as you realize the name is no longer appropriate, take a moment to change it.  It’s easier than you think.  With modern search and replace tools (or the old fallback “perl -p -i -e ’s/old/new/g’ *”), version control, and even IDEs with refactoring menus, there’s just no excuse for a bad name.

This entry was posted on Saturday, May 27th, 2006 at 8:00 pm and is filed under Code. You can follow any responses to this entry through the RSS 2.0 feed. Responses are currently closed, but you can trackback from your own site.