Saturday, August 29, 2009

Long and Short of Naming

The point of good naming is not to make the names long but to make them clear and obvious. 

A coworker showed me some code where variable namess were descriptive, but rather similar to each other in shape and containing some of the same words.  He then showed me the same code where the variable names were replaced with X, Y, and Z to illustrate that (even in this case) shorter names were superior. He was right. 

When I'm looking at code, I need to see its structure. When long identifiers obscure the structure, will struggle. 

I also need to see all the ways a given variable is used in the function. If I can barely tell the difference between variable names (ie I have to READ them all to tell them apart) then it's more work. 

Is a short, distinctive, nonsensical name better than a long hard-to-distinguish name? Can that be true? In the context of a passage of code (not just an isolated name) it certainly can be true.  A short, distinct, and clear name is even better.

Good naming has never been about making names long. It has always been about making them clear.

Typically overlong names are a result of messy context. I really don't need to see ClientAddressStreetString and try to tell it from ClientAddressZipcodeString.

These names are long and similar in shape. I can read them and tell them apart, but the change is 3/4ths of the way through the pile of syllables.

If the code is complex enough it might be better if the strings were A1 and A2 so I could see each at a glance. In this case, I think I would rather see them called "zip" and "street" so that I could tell them apart easily and they would make sense in the context of ClientAddress.

When you are tempted to make overly long names, consider these concepts instead:
  1. If you add type context and are not writing a type conversion, you're probably doing something wrong. If the only form of the variable is a string, then "string" context wart is entirely unnecessary as a suffix or prefix.
  2. If you have to add a class name to a variable as a wart (eg "ClientAddressStreet") then maybe you are doing the work in the wrong place. The name should make sense in its context, so that context warts are unneeded.
  3. A short bad name is better than a long bad name.
  4. The similarity of multiple names destroys readability. Consider reading a book where the main characters all had names that were all too similar:
    George's son Georgy turned to Geoffrey's daughter Georgina whose question about Geoffrey and Geordi had clearly aroused Geoffrey's son George's curiosity. He feared Georgia would realize that her past history with George's Georgina was no longer a secret to Geoffrey. Would Georgia maintain her silence? "Georgina," he asked, "talk to me of Geography and Geology and let's leave Georgia with Georgy to discuss choreography."
  5. If your long names start to obscure the path, we can't call them "good names".
  6. Even in the face of long bad names, abbreviations and mental mapping are not good things. They may happen to be less bad than some other bad things you could have done instead, but they're still not good names.
Any misunderstanding of "good naming" to mean "good and long" is indeed a misunderstanding. Longer names are not, pound for pound, better than shorter names in a given context.

3 comments:

  1. Context warts ? Brilliant...

    I can't wait to use that this week...

    ReplyDelete
  2. A lot of people don't realize that StreetAddress.city is already in context, and StreetAddress.StreetAddressCityOfResidence is overboard.

    In StreetAddress class, there is a fun problem. You will see "Address Line 1" and "Address Line 2" -- doesn't that imply an array of N address lines? Aren't numeric tail warts a smell?

    ReplyDelete
  3. Thanks for the post and that clarification, Tim. I have also seen lots of examples of HomeAddress.AddressLine1 instead of Home address.Line1. In fact, all I could think of while taking the post was that instead of that long name, add that context.

    Thank you for clarifying.

    ReplyDelete