Search code examples
naming-conventionsnaming

How do we shorten long variable name?


Normally we hear advice like using a descriptive variable name to convey the intent. The descriptive name sometime gets longer, if we avoid abbreviation.

However there should be a limit where the variable name can be easily consumed in human's eye. For instance, I see something similar in my ex-company:

int thisIsASuperLongVariableNameHere vs int thisIsASuperLongVariableNameThere vs int[] thisIsASuperLongVariableNamesHere

If we only glance through those variable names, they all look very similar, and our brain cannot catch the different efficiently.

So my question is, what is the max length of variable name that human can consume effectively?

If the variable name exceed the length, what is the standard approach to shorten them?


Solution

  • Standard approach:

    There is no "standard approach" to shorten them.

    I found some good guidelines though in Steve McConnel's Code Complete (Chapter 11).

    If you have access to it give it a look (it's a worthy book to have, in any case). Unfortunately I don't think I can quote his whole list without copyright troubles.

    Edit: I stumbled upon a post on another site that quotes the whole section of the book where those guidelines are listed.
    I'm not sure how legal that quotation is, so I don't repeat it here.
    However as it can be of help to someone and I mostly clarified that linking to it is ok*, I decided to do add a link.
    Mind that the rest of the book's chapter contains yet a lot more information on naming, and even on short names/prefixes in particular.
    And the remainder of the book has a wealth of information that any developers should know, largely still relevant today 13 years after its publication.
    So I recommend all the readers to buy the whole book even if the quote I linked fulfilled their current needs, and to consider that quote just an appetizer for it.


    Max length:

    • There's no consensus yet on a "max length"; it's probably recognized by most that it would be better to not exaggerate in length, but there's no established consensus (or even much discussion) as to what degree.
    • Code Complete has a nice reference to a 1990 study where it was found that the effort required to debug a program was minimized when variables have names that average 10 to 16 characters, and “programs with names averaging 8 to 20 characters were almost as easy to debug”.
    • There are probably more recent studies (either squarely on programming or on reading in general), but I'm not aware of any.
    • Most of all use your good sense, keeping in mind that the advantage in clarity that longer names convey will often outweigh their disadvantages in reading speed and potential mix-ups (so when in doubt it's better to lean towards verbosity)
    • You should keep in mind that it makes sense to aim at different lengths in different situations.
      For example, in Clean Code, Uncle Bob suggests that

      The length of a name should correspond to the size of its scope

      Generally this can be simplified to:

      • for local variables of very short methods it can be reasonable to use even single-letter names
      • for most other stuff use descriptive, reasonably long names
      • and for rarely used stuff consider to use even more verbose ones.
    • (this applies to names' decisions in general)
      When you're uncertain about some name discuss that (even briefly) with your colleagues.
      This is not guaranteed to give you better names, but the others' approval will let you go on with the rest of your work with more confidence.
      Beware that this might make you tilt towards (too) bad names, as you'll easily get hasty approvals from busy or uncaring colleagues; their approval will protect you from complaints in the future, but you might still have caused trouble to newer employees or even to your present hardly-remembering-to-ever-wrote-that selves.

    Too similar names:

    As to the example of names you made, in general it's better to just strive to avoid names so similar, if you can.
    If your naming conventions don't forbid it, you can often use some simple trick to skirt the similarity:

    thisIsASuperLongVariableName_Here
    thisIsASuperLongVariableName_There
    thisIsASuperLongVariableName_Here_Array