Saturday, August 29, 2009

Long and Short of Naming

To be clear, long names that look too much alike are not superior to short names that look different. 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 variables were very similar to each other in shape and contained some of the same terms in them. He then showed me the same code where the variable names were replaced with X, Y, and Z so that I could see that (in this case) shorter names were superior. Mind you, he was right.

If I'm looking at the code, I absolutely do need to see the structure thereof. If long obscure the structure, then I'm not going to love it. 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 we've lost something. In such an instance a short, distinctive, nonsensical name is better than a long hard-to-distinguish name.

Never has good naming 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 hopelessly similar in shape. I can read them and tell them apart, but the change is 3/4ths of the way through the pile of characters. If there is much going on, it might be better would it be if the strings were A1 and A2 so I could see the differences 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.

If you make overly long names, consider these concepts:

  1. If you add type context, and are not writing a type conversion, you're probably doing something wrong. If the only street line is a string, then "string" 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. Similarity of multiple names destroys readability. Consider reading a book where the main characters all had names which were all too similar:
    Georgy turned to Georgina whose question about Geoffrey and Geordi had clearly aroused George II's curiosity. He feared Georgia would realize that her past history with 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 George II to discuss choreography."
    At some point, you wish someone's name was "Hank", yes?
  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.