< Free Open Study > |
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 GuidelinesHere are several guidelines for creating abbreviations. Some of them contradict others, so don't try to use them all at the same time.
Phonetic AbbreviationsSome 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:
Comments on AbbreviationsYou 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 TableC ******************************************************************* 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:
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.
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 > |