Difference between revisions of "Standards of Nomenclature and Semantics"

Revision as of 12:13, 19 April 2006

When coding in any language, on any platform, it is necessary to employ a great deal of thought in terms of what you are going to name your components, variables and objects. The following document is not a rigid standard that must be stuck to, but rather a guideline that will attempt to explain most of the steps that are necessary in writing understandable code (and when I say understandable, I mean understandable by other coders, not just you).

Descriptive Names

The first thing to discuss under the topic of nomenclature and semantics is descriptiveness of names. Something that many people do not understand (Microsoft included, in many cases) is that all names MUST be descriptive. For example, consider the following code:

   Dim Date1 As Date, Date2 As Date
   
   Date1 = Date
   Date2 = DateAdd("d", 7, Date1)

On its own, this code makes perfect sense: you assign today's date to Date1, and then add 7 days and assign this to Date2. Thus, this code is seemingly OK. However, in a situation where you have a lot of code in one routine, and the dates are declared and assigned at the top of the routine, there is no way that you or anybody else is ever going to remember which variable is which or how they are used.

Now consider this code:

   Dim dtToday As Date, dtNextWeek As Date
   
   dtToday = Date
   dtNextWeek = DateAdd("d", 7, Date1)

As you can see, it would now be clear to anybody what the purpose of these variables are, wherever they are in your code, and it is much easier to remember which is which while coding.

Naming Files

While the standards of naming files may be obvious to many people, it is all too often that you see projects with forms called 'Form1', 'Form2' etc. and modules called 'Module1'. Thus it is necessary to explain the naming standards for files.

The generally accepted method for naming files is to choose a descriptive name for the file, and then prefix it according to the file type, using the correct prefix from the table below:

For example you may have the following files in your application:

• frmMain
• frmAbout
• frmPrintBookings
• frmPrintInvoice
• frmCalendarView
• modMain
• modSettings
• modDeclares

From the names of the files, it is obvious what the purpose of each is, and thus the code is easily maintainable.

Naming Controls

It is very important to properly name controls so that, in your code, you know exactly what you are dealing with, and so that other people who will read your code will know what you are doing when you access a control's properties/methods/value(s). It is also important that you name ALL your controls properly. There is no point naming just the ones that you will use in your code. If, for example, a textbox has a descriptive label, the label must be named in the same fashion as the textbox. The reason for this is that, on large forms where there are many controls, and you may not be able to see all the controls at once, it is much easier to select controls from the combobox above the properties box than with the mouse. If your controls are named 'Label1' etc. then neither you nor anyone else will be able to find them.

Controls are named in a very similar fashion to files - a descriptive name preceeded by the correct prefix, corresponding to the control type. The following is another list of prefixes that describe which go with which control type:

For example, a dialog will normally have some controls named something like the following on:

• txtName
• txtAddress
• cboYear
• cmdOK
• cmdCancel

Once again, from these names, it is obvious what the purpose of these controls are, and thus it will be clear in code what you are doing with the data that the user entered.