Naming Objects and Variables


The naming of objects should take into account the following details:

  • Entity description

  • Name length

  • Abbreviations

  • Name formatting

Entity Description

It is common knowledge that variables, procedures, and objects should be named after the entities or processes that they represent. Therefore, just to type a full description is a good start. The advantages of this approach are

  • Nobody will be confused about the purpose or contents.

  • It makes for easy-to-read code, since no cryptic abbreviations are used.

  • It makes the entity name easy to understand and memorize, since the description closely matches the entity.

Just compare the names in the following table:

Good

Bad

©Current Date

@D

©Activity Count

@ActNum

©Equipment Type

@ET

Calculate Order Total

RunCalc

Note 

Such descriptions are usually just the basis for a name. Standards generally prescribe the use of different prefixes or suffixes to further describe other attributes such as the type of object, the data type of a variable, and the scope.

A very common mistake is to use computer-oriented terminology instead of business-oriented terminology. For example, ProcessRecord is a confusing name for a procedure. It should be replaced with a business description of the process, such as CompleteOrder.

Name Length

Unfortunately, if you are too literal in naming procedures according to their business descriptions, you end up with names like:

  • PickupReconciliationlnventoryldentifier

  • TotalAmountOfMonthlyPayments

  • GetParentOrganizationalUnitName

Although SQL Server supports the use of identifiers up to 128 characters long, research has shown that code in which most variable names are between 8 and 15 characters in length is easiest to develop, read, debug, and maintain. This fact does not imply that all of your variables must have lengths in that range, but you can use it as a rule of thumb.

Another rule of thumb is to try to limit names to three words. Otherwise, names become too long and thus more difficult to use and maintain.

You could go to an extreme in the other direction, as well. If you are using a variable as a temporary counter in a loop, you could name it @I. But even in such a case, it might be easier to understand your code if you name it ©OrderItem.

Abbreviations

A simple way to reduce the length of a name is to abbreviate it. If you can find an abbreviation in a thesaurus or dictionary, you should use it. You will avoid potential confusion. If not, you can simply remove vowels (except at the beginning of the word) and duplicate letters from each word, as in these examples:

  • Current = Crnt

  • Address = Adr

  • Error = Err

  • Average = Avg

You could also use the first letters of words or the first few letters of a word, but make sure that the names you create will not be confused with other, more common abbreviations. For example, you could abbreviate Complete Order Management to COM, but Visual Basic programmers might assume it stands for "component."

If you do not want to confuse readers of your code (such as the fellow programmers trying to maintain it months after you have taken early retirement and moved to a remote tropical island), you should avoid using phonetic abbreviations like

  • 4tran (Fortran)

  • xqt (execute)

  • b4 (before)

Abbreviations are great, but you should be careful not to confuse your colleagues. Try to be consistent. If you start abbreviating one word, you should do the same in all occurrences (variables, procedures, objects). It is potentially confusing to abbreviate the word Equipment as Eq in one case and leave the full word in another case. You will cause confusion as to which to use and whether they are equivalent.

To avoid confusion, you can write a description (using full words) in comments beside the declaration of a variable, in the definition of an object, or in the header of a procedure; for example:

      declare OErrCd int  -- Error Code 

Ideally, the use of abbreviations should be defined, documented, and enforced as a naming convention and therefore applied consistently by everyone on the team.

Name Formatting

I have heard endless debates about formatting identifiers. To underscore or not to underscore—that is the question:

  • LeaseScheduleld

  • lease_schedule_id

The truth is it does not matter. You should avoid mixing these two conventions because developers will never know what they have used for which variable. Unfortunately, you can catch even Microsoft developers mixing them. They are just human beings, after all.

In some rare cases, I believe it is justifiable to mix these two conventions in one identifier. For example, I like to note modification statements at the end of the name of a trigger (Insert and Update trigger on Orderltem table):

      trOrder!tem_IU 

I also use an underscore to divide table names joined with a foreign key (such as a foreign key between Order and Orderltem tables):

      fk Order Orderltem 




Microsoft SQL Server 2005 Stored Procedure Programming in T-SQL &  .NET
Microsoft SQL Server 2005 Stored Procedure Programming in T-SQL & .NET
ISBN: 0072262281
EAN: 2147483647
Year: 2006
Pages: 165

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