11.6. Creating Short Names That Are Readable

 < Free Open Study > 

The desire to use short variable names is in some ways a remnant of an earlier age of computing. Older languages like assembler, generic Basic, and Fortran limited variable names to 2 8 characters and forced programmers to create short names. Early computing was more closely linked to mathematics and its use of terms like i, j, and k as the variables in summations and other equations. In modern languages like C++, Java, and Visual Basic, you can create names of virtually any length; you have almost no reason to shorten meaningful names.


If circumstances do require you to create short names, note that some methods of shortening names are better than others. You can create good short variable names by eliminating needless words, using short synonyms, and using any of several abbreviation strategies. It's a good idea to be familiar with multiple techniques for abbreviating because no single technique works well in all cases.

General Abbreviation Guidelines

Here are several guidelines for creating abbreviations. Some of them contradict others, so don't try to use them all at the same time.

  • Use standard abbreviations (the ones in common use, which are listed in a dictionary).

  • Remove all nonleading vowels. (computer becomes cmptr, and screen becomes scrn. apple becomes appl, and integer becomes intgr.)

  • Remove articles: and, or, the, and so on.

  • Use the first letter or first few letters of each word.

  • Truncate consistently after the first, second, or third (whichever is appropriate) letter of each word.

  • Keep the first and last letters of each word.

  • Use every significant word in the name, up to a maximum of three words.

  • Remove useless suffixes ing, ed, and so on.

  • Keep the most noticeable sound in each syllable.

  • Be sure not to change the meaning of the variable.

  • Iterate through these techniques until you abbreviate each variable name to between 8 to 20 characters or the number of characters to which your language limits variable names.

Phonetic Abbreviations

Some people advocate creating abbreviations based on the sound of the words rather than their spelling. Thus skating becomes sk8ing, highlight becomes hilite, before becomes b4, execute becomes xqt, and so on. This seems too much like asking people to figure out personalized license plates to me, and I don't recommend it. As an exercise, figure out what these names mean:

ILV2SK8

XMEQWK

S2DTM8O

NXTC

TRMN8R


Comments on Abbreviations

You can fall into several traps when creating abbreviations. Here are some rules for avoiding pitfalls:

Don't abbreviate by removing one character from a word Typing one character is little extra work, and the one-character savings hardly justifies the loss in readability. It's like the calendars that have "Jun" and "Jul." You have to be in a big hurry to spell June as "Jun." With most one-letter deletions, it's hard to remember whether you removed the character. Either remove more than one character or spell out the word.

Abbreviate consistently Always use the same abbreviation. For example, use Num everywhere or No everywhere, but don't use both. Similarly, don't abbreviate a word in some names and not in others. For instance, don't use the full word Number in some places and the abbreviation Num in others.

Create names that you can pronounce Use xPos rather than xPstn and needsComp rather than ndsCmptg. Apply the telephone test if you can't read your code to someone over the phone, rename your variables to be more distinctive (Kernighan and Plauger 1978).

Avoid combinations that result in misreading or mispronunciation To refer to the end of B, favor ENDB over BEND. If you use a good separation technique, you won't need this guideline since B-END, BEnd, or b_end won't be mispronounced.

Use a thesaurus to resolve naming collisions One problem in creating short names is naming collisions names that abbreviate to the same thing. For example, if you're limited to three characters and you need to use fired and full revenue disbursal in the same area of a program, you might inadvertently abbreviate both to frd.

One easy way to avoid naming collisions is to use a different word with the same meaning, so a thesaurus is handy. In this example, dismissed might be substituted for fired and complete revenue disbursal might be substituted for full revenue disbursal. The three-letter abbreviations become dsm and crd, eliminating the naming collision.

Document extremely short names with translation tables in the code In languages that allow only very short names, include a translation table to provide a reminder of the mnemonic content of the variables. Include the table as comments at the beginning of a block of code. Here's an example:

Fortran Example of a Good Translation Table
C ******************************************************************* C    Translation Table C C    Variable    Meaning C    --------    ------- C    XPOS        x-Coordinate Position (in meters) C    YPOS        Y-Coordinate Position (in meters) C    NDSCMP      Needs Computing (=0 if no computation is needed; C                                 =1 if computation is needed) C    PTGTTL      Point Grand Total C    PTVLMX      Point Value Maximum C    PSCRMX      Possible Score Maximum C *****************************************************************

You might think that this technique is outdated, but as recently as mid-2003 I worked with a client that had hundreds of thousands of lines of code written in RPG that was subject to a 6-character variable-name limitation. These issues still come up from time to time.

Document all abbreviations in a project-level "Standard Abbreviations" document Abbreviations in code create two general risks:

  • A reader of the code might not understand the abbreviation.

  • Other programmers might use multiple abbreviations to refer to the same word, which creates needless confusion.

To address both these potential problems, you can create a "Standard Abbreviations" document that captures all the coding abbreviations used on your project. The document can be a word processor document or a spreadsheet. On a very large project, it could be a database. The document is checked into version control and checked out anytime anyone creates a new abbreviation in the code. Entries in the document should be sorted by the full word, not the abbreviation.

This might seem like a lot of overhead, but aside from a small amount of startup overhead, it really just sets up a mechanism that helps the project use abbreviations effectively. It addresses the first of the two general risks described above by documenting all abbreviations in use. The fact that a programmer can't create a new abbreviation without the overhead of checking the Standard Abbreviations document out of version control, entering the abbreviation, and checking it back in is a good thing. It means that an abbreviation won't be created unless it's so common that it's worth the hassle of documenting it.

This approach addresses the second risk by reducing the likelihood that a programmer will create a redundant abbreviation. A programmer who wants to abbreviate something will check out the abbreviations document and enter the new abbreviation. If there is already an abbreviation for the word the programmer wants to abbreviate, the programmer will notice that and will then use the existing abbreviation instead of creating a new one.

The general issue illustrated by this guideline is the difference between write-time convenience and read-time convenience. This approach clearly creates a write-time inconvenience, but programmers over the lifetime of a system spend far more time reading code than writing code. This approach increases read-time convenience. By the time all the dust settles on a project, it might well also have improved write-time convenience.


Remember that names matter more to the reader of the code than to the writer Read code of your own that you haven't seen for at least six months and notice where you have to work to understand what the names mean. Resolve to change the practices that cause such confusion.

 < Free Open Study > 


Code Complete
Code Complete: A Practical Handbook of Software Construction, Second Edition
ISBN: 0735619670
EAN: 2147483647
Year: 2003
Pages: 334

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net