Website Design United States, Website Design California, Website Designing United States, Website Designing California

Naming Conventions


Are naming conventions really necessary when programming?

There is a lot of debate over this topic. Are naming conventions really worth it? Aren't they a hassle to learn and use? Can't you code quicker if you don't using naming conventions?

If you’re not familiar with naming conventions, here is how they work.

When most people hear of naming conventions, they automatically think of Hungarian Notation. (HN) If you have seen naming conventions before, but are not familiar with the term "Hungarian Notation", you are probably familiar with how it looks.

Hungarian Notation is a naming convention invented by Charles Simonyi from Microsoft. Some examples of HN are: m_nSize, hwndParent and lpszFile.

Traditional Hungarian Notation uses various prefixes to identify the scope and type of a variable.

Lets examine the following variable in C++.

lpszFileName
  • The lp designates this is a Long Pointer.
  • The sz designates this is a string.
  • The File is the name of the variable.

So, in reading the variable lpszFileName, you would read it as "a long pointer to a string holding the file name". If that variable were of a module level scope, it would be prefixed with 'm_'. So the module level version of that variable is: m_lpszFile.

There are several advantages to using HN. As we just saw, using HN tells us the scope and type of a variable, without using a very long variable name. It also means you can figure out what type of variable is used, even when reading printed code. Basically, using a naming convention is an extension of commenting. It allows you to understand what a variable is for, just by reading the name.

There are some disadvantages to using naming conventions though...

First, what happens when you change a variable type? You have to go change ALL the instances of that variable within your code. Some editors have some pretty sophisticated find-and-replace tools, so this wouldn't be that big of an issue... but it still needs to be done.

Second, what happens if you upgrade your language, and what was a 16-bit integer is now a 32-bit integer? Now you have to go change portions of your code so your naming convention still fits...

Third, naming conventions can defeat the purpose of encapsulation. Encapsulation means "black box" right? So why does the programmer need to know what specific type is being returned? They just create a variable of that class, and then use it. Who cares if it’s a long, or a string, or an object.

So, do the disadvantages outweigh the advantages? No... I would still use naming conventions for the simple fact of readability. As I stated before, using naming conventions in your programming allows you to read your variable types (and their purpose) at a glance... No need to go looking for a declaration.

My style:

I prefer to use an abbreviated version of the HN. I generally use a single letter prefix for types, a single letter prefix for scope (with the procedure scope having no prefix) and no underscores.

So a module level string variable would be named like this: msFileName.

Here is a listing of some naming conventions I use. Not all of them port over to every language... and not every language has type variables. But these can be ported fairly easy from language to language.

      Prefix
      s String
      t
      b
      i
      l
      f
      d
      cur
      dte
      o
      v
      Type
      c Character
      Byte
      Bool
      Integer
      Long
      Float (single)
      Double
      Currency
      Date / Time
      Object
      Variant

As you can see... I try to stick to a single letter prefix. But in some cases, this is not an option if you want to keep the prefixes logical.

For scope, I use only two prefixes:
Prefix Scope

      Prefix
      m
      g
      Scope
      Module level
      Global

I rarely use global variables or objects anymore... I try to avoid them, simply for OO reasons... but that is another topic in itself... :)

I also use a naming convention for all controls. I use a three-letter prefix for controls. Here are some of the prefixes I use:

      Prefix
      txt
      lbl
      cmd
      chk
      opt
      lin
      lst
      cbo
      fra
      mnu
      Control Type
      Text box
      Label
      Command Button
      Check Box
      Radio button (option button)
      Line
      List box
      Combo box/dropdown box
      Frame
      Menu
Logical Object Names

Now we get into syntax behind your object name. I say object, since this logic also applies to controls, forms and classes.

When naming your objects, there are a few things you need to keep in mind.

First, the name should be descriptive of what that object contains or does.

For example:

  • sFirstName // Good
  • sSomeData // Bad

The first object would appear to be a string to hold the First Name. This provides dual functionality. First, as stated, its descriptive of what the object is for. Second, other people reading your code can easily figure out what that object is, just by the name.

The second object appears to hold Some Data. What is Some Data? It’s a string… but what is it used for?

Second, your objects should be named consistently.
  • iNum // Good
  • iNo // Good - just inconsistent with the first style

Either example is fine (I prefer the first) but you need to use that same name in other places. Don’t call the variable iNum in one routine, and call it iNo in another… and iNumber in yet a third… be consistent.

Finally, you want your object names to be short. You don’t want to spend all day typing in a name. So keep them clear, yet concise.

Oh, and watch your spelling… even though it is code, and you may be the only one who ever sees it… don’t misspell your object names….

For more information, I suggest reading:

Hungarian Notation - The Good, The Bad and The Ugly
Hungarian Naming Convention

Author Information:

Eric D. Burdo

http://thenxtstep.blogspot.com/

Comments:

Add your comments here.

Name

Comment

You can also send feedback to feedback@programmers-corner.com

Mike Guyot - April 23, 2005 3:04 AM

I strongly disagree with most of what you say, even though I know it's considered to be received wisdom. I have to admit that prefixing a variable name is extremely convenient when writing class modules, since one can use gName to name the global variable which is set to the value of mName, the module level variable with a statement like gName=mName. It lets us see effortlessly that the same variable name is being used in both the global and the module-level contexts. In this case, we in effect are ignoring the prefix, however. In accord with the principle of encapsulation, we are going to use only the mName variable in the class module, and only the gName variable in the calling procedure, except when we are setting the one equal to the other. Even if we don't use the m and the g, there will never be any confusion about which variable we are using except when we equate the two.
You say, ". . . using naming conventions in your programming allows you to read your variable types (and their purpose) at a glance... No need to go looking for a declaration." This strikes me as an extremely weak reason. If you don't wish to have to go looking for the declaration, it is extremely easy to print a page or two of declarations and leave it lying next to your monitor. If you declare the variables in the same order as you use them in, it becomes very easy to find the one you need to type-check, because you can look for the three or four other variables which are being used in close proximity to the one you need, and find it fast. The amount of effort you use trying to puzzle out the meaning of a variable name like lpszFileName is at least comparable to the amount of time you would spend glancing at your printed variable declarations.
Your next apologia is "readability". Compare a conventional variable named gsContext_Results or iNum to an almost normal word like WorkerCount. gsContext_Results is a global string variable naming results probably extracted from some context or other. Results can describe anything from the outcome of a coin toss to the big bang. Since gsContext is not a normal word, one will probably have to mentally pronounce it when reading it. If you don't distinguish each of the letters in the prefix, they are not serving their function. If you do, you have to notice each one, mentally annotating the name. This has to be slower and somewhat distracting. WorkerCount, by contrast, doesn't use a naming convention, yet is highly descriptive. It obviously is the number (not the "num") of workers in some category or other. We are almost certainly justified in expecting it to be an integer, since, if there are fractional workers in our calculation, the variable probably should have been named WorkerRatio, or something of the sort.
As for your control naming convention, I would prefer to name a list box NameList, which the eye can read and instantaneously transfer to the mind without translation, instead of lstNames, which my eye has to pause on in order to break it down, since I immediately notice that lst is not a word, even before I notice anything else about lstNames.
Finally, let me just point out that the objective of making varialbe names short is in direct conflict with the objective of making the code readable. You can't
have both. I personally find the use of "num" quite irritating, especially when people start naming variables oldnum, newnum, subnum, and so on, which unfortuately is common. And whatever is irritating obviously reduces the readability.

Eric D. Burdo - April 25, 2005 11:00 AM

To refute a couple of your examples:

Printing out the declarations: I work from about 3 different computers on the same project. That means 3 different sets of printouts (or carrying them around with me). Adding a letter or two at the beginning of a variable is easier for me.

WorkerCount would be declared as lWorkerCount or iWorkerCount. Signifying that it is a Long or Integer. WorkerCount is a excellent variable name... you just don't know the type.

gsContext_Results is a lousy example of a good variable name. Context_Results means absolutely nothing (as you stated in your comment). Variable names should match what they contain. If your storing High Scores, then you would use HighScores, and prefix it with the scope and type.

I agree with you on a lot of your comment. Readability is an important issue with naming variables. Num, SubNum, OldNum etc are a poor way to name your variables, regardless of wether or not use use a prefix to denote their scope and type.

 















 


© 2008-2009 dotnet4all.com