Delphi Standards: Naming component instances

It’s standard practice to name component instances referenced in code. It’s also helpful to name components that appear in the tab order. Typically a name consists of a description and a type abbreviation.

There is some debate, although I’ll argue it’s unfounded, as to whether the abbreviation should be added as a suffix or a prefix. See the article: “Delphi Standards: The Case for Suffixes” for a complete discussion.

When naming a component instance the two main goals are to:

1. insure uniqueness (for example to avoid a conflict between the name for the find button and the find edit box) and to
2. improve code readability.

In the past, a name also helped to identify the specific type. This is less important today. With Delphi’s tooltip symbol insight you get type information by pointing at an identifier. As you’ll see later, this fact will influence our abbreviation choices.

Knowing that consistency is important; how do we get everyone on a development team to abbreviate in a consistent manner? The standard approach has been to make a list of abbreviations for each type. You can find several examples on the web.

The problem with lists

At a glance, lists seem to be a good way to gain consistency, but practice doesn’t bear this out. Developers often find lists more bother than they’re worth. Lists don’t work because they:

1. are cumbersome to use – team members must either memorize or look up the abbreviation for each type
2. lack flexibility – every time a new type is added, a new abbreviation must be added too, and
3. slowly become neglected over time.

While lists are often initially adopted with conviction, teams usually slip away from them as projects progress. The larger the team, the larger the project, and the higher the pressure the more likely slippage is to occur. A core set of abbreviations usually sticks, but inconsistency becomes common as new and uncommon types are introduced.

A better solution: rules based naming

Instead of a long list of all the abbreviations, using a set of rules to create names provides a simpler and more flexible approach. The rules will be complemented with a small list of just the exceptions.

Also important is minimizing the number of abbreviations to only those that are absolutely necessary. As previously mentioned, we don’t need to be too specific because tooltip symbol insight will help when we need more information. Also note that longer and more specific abbreviations are harder to quickly interpret, making the code less scanable.

As you name components in your application, apply the following rules in order:

1. Remove the following characters. Stop applying rules if you reach 3 letters.
   1. “T”
   2. any vendor specific characters(cx, ww, rz, pp, etc.)
   3. DB
   4. any adjectives (for example, “main” from TMainMenu )
   5. double consonants
   6. vowels – left to right
2. Check the exceptions list.
3. If you’re left with an awkward or long abbreviation, don’t make things difficult:
   1. For uncommon types, apply just rules 1a,b and c. *
   2. For common types, add an appropriate abbreviation to the exceptions list. **

*This results in a lengthier but usually clearer abbreviation.

**Remember be stingy about this! Keep the exceptions list small.

A few examples:

As you review the examples, it bears repeating that having an abbreviation that provides specific type information is not a goal. Tooltip symbol insight is available if we need more detail. The lack of specificity helps reduce the number of abbreviations so you’ll remember many without ever applying the rules.

Note that the rules are meant to yield improved consistency, not perfect consistency. Some sacrifice is needed to keep things simple. Without it, the rules could become just as unwieldy as the lists they sought to replace. Keep ease of use in mind as you make adjustments to better fit your team.

Conclusion

A rule based system for naming component instances provides more consistency than a static list. Being only as specific as is needed for uniqueness and readability is a key to making the naming system simple and successful. To get started, gather a team consensus around a simple set of rules to name your component instances.

Questions or Comments for the author

Copyright ©2003 Rick Ross