What's in a name?
Part I: Variables and methods

Manohar Kamath
June 9th, 1999

If only the Bard were a programmer would he know the importance of names. Anyone who has looked at someone's code has an opinion on choosing names within your program. This issue is important not only in ASP but in any other programming language. This article makes an attempt to educate beginners on choosing names for variables, constants and other named objects within ASP.

In this series I will talk about using some conventions in naming variables, constants and methods. Using a convention is upto your convenience. It only helps you to understand your own code at a later date. Also, using a convention to name objects in the code helps others to understand your code easily and also to debug if necessary. There are hundreds of conventions programmers use and you can probably find these at the beginning of almost any book.

This installment deals with naming two important things - variables (and constants) and methods.

Dissecting a variable
I will start out with one variable as an example:

lsUserName

The above variable name comprises three parts

1. The scope prefix letter. In this case it is "l" that suggests that the variable is of local scope within a function or a subroutine. A scope is the area within the ASP page where you can actually "see" the value of the variable. E.g. You declare the variable within a page, and if you can not see the value within a subroutine, it is out of scope in that subroutine.
2. The data type prefix letter. The "s" in this case suggests that the variable is of string data type.
3. The actual name. "UserName" indicates that the variable holds a user name or a login name etc.

An example of a method where such a variable could be used is as follows:

Function myFunction()
  Dim lsUserName
  ..
  ..
End Function

The scope of the variable lsUserName is the function myFunction, meaning you can not access this variable outside the function.

The second letter represents the datatype of the variable. Although all the variables within server-side script are variant datatypes, I choose to consider them of the type they are expected to hold in them. E.g. If a variable is expected to hold a large number, I consider it to be a long data type.

Here is another sample code

<%@Language="VBScript" %>
<%
  ' This variable is global, visible to entire page
  Dim gsUserName
  gsUserName = Request.QueryString("UserName")

  ' Call the method sayHello and pass the global variable as an argument
  ' Although this is redundant, it is for illustration purposes only
  sayHello(gsUserName)

  ' Call the sayGoodBye method
  sayGoodBye()

' The variable psUserName is  visible to this subroutine
' only. However, it is declared as a parameter
Sub sayHello(psUserName)
  Response.Write("Hello, " & psUserName)
End Sub

Sub sayGoodBye()
  ' This variable is local to the subroutine
  Dim lsMsg
  lsMsg = "Please Come again."

  ' The variable gsUserName is visible here too
  Response.Write("Goodbye, " & gsUserName)
  Response.Write(lsMsg)
End Sub
%>

In this example, I illustrate the use of variables of global scope (In ASP terms, of Page scope). The function sayHello gets the user name in a parameter (hence the parameter scope). The function sayGoodBye, however, accesses the variable within the page scope.

A sample convention

Scopes
g - Global scope. The variable is used across all the functions and subroutines. Use this for page-level variables. E.g. Any variable that holds a querystring variable, to be used by many methods.

l - Local scope. Used within a subroutine or function. Can not be accessed in other methods.

p - Parameter scope. These are the parameters received by a function or a subroutine. These are not declared using Dim (in VBScript) or var (in JavaScript)

Data types
i - Integer
l - Long
f - Float (double or single)
d - Date
a - Array. This is an exception to the rules we've seen so far. Although the array can be expected to have a specific data type, we will not use a third letter to denote that.
s - String
c - Constant. Another exception to the rule. Constants can be of different data types.
o - Object. Things like a RecordSet, Connection, etc. fall into this category.

There is some rationale behind choosing prefixes like "f" for float - you don't encounter float data types as many times as you do others. Also, I have separated integer and long from just being a numeric as there are times we expect the variable to hold small numeric values (in a counter, flag etc) and sometimes huge values (dollar amounts).

I could add more data types to the above set, but it would just add to the complexity of the code. For example, if you always used  "Numeric" data type instead of integers and longs, just use "n" to mean Numeric.

TIP: If you choose a convention, stick to it. Also, try documenting your convention so that other people will have easy time going through your code.

Choosing variable names
It is sometimes difficult to come up with a name for a variable, especially if you have numerous other variables that indicate the same. E.g. You have two variables that need to hold a person's name before and after a name change. In this case, the variables point to the same thing - a name. However, choosing variable names lsInitialName and lsFinalName clears up the ambiguity. Here are some guidelines:

• Use meaningful names for all your variables. A variable name like "lsFirstName" tells me more about the variable than "lsFName" or "lsNameF." Using meaningful name brings with it some pain - that of long names. Many programming languages have a restriction on the length of variable names (In VBScript, I think it is 255). So be careful when using a name like "ls_I_Dont_know_why_I_am_Using_a_Name_as_long_as_this". Not to mention the pain in just typing the variable name.
• Capitalize the initials of individual words. This makes the variable name easy to read
• Do not use short forms of names unless absolutely necessary. Use lsFirstName instead of lsFName.
• You may want to use a underscore character ("_") when you have a long name, in separating individual words. I usually don't use one, but it is a good idea to distinguish between words. Not using one saves you space when using long names.

Option Explicit
Using Option Explicit at the top of every page almost eliminates chances of using undeclared variables. Without using the Option Explicit, your code may run fine, but the results may not be what you expected. An example code is as follows:

<%@Language=VBScript %>
<% Option Explicit %>
<%
  Dim gsUserName
  gsUserName = "John Doe"
 
  ' This will cause an compile error saying the
  ' variable has not been declared
  Response.Write(lsName)
%>

You need not worry about this in JavaScript since it checks for any undeclared variables before the code is run.

Naming Methods

Methods are pieces of code which do some action. In VBScript, we have two different types of methods. Subroutine, indicated as Sub, that does something but does not return a value. A function on the other hand returns a value. In Javascript, there is no concept of a subroutine, everything is a function and the function may return nothing or a value.

Naming a method is simpler than naming a variable. Here are some guidelines

1. Start the method name with an action word. Action words denote what is that you do in the method, examples could be "get", "set", "retrieve", "display", "create".. the list goes on. This will help others understand what you are trying to do within the method.
2. Start the word in lower case, capitalize the initials of subsequent words in the name. E.g. getID(), setUserName(), createGraph() etc.
3. Keep the names short, short enough to distinguish between all the methods you have in the page. Unlike variables, methods need not have long names. Usually, there will be more variables than there will be methods on a page. So it is easier to differentiate between various methods than to differentiate between variable names

TIP: Improve the readability of your methods by documenting them. Mention what they are supposed to do, input parameters, return values, etc.

A complete example

To illustrate what we have learnt so far, I put together this example. The example simply prints some friendly messages on the screen.

<%@Language=VBScript %>
<% Option Explicit %>
<%
' Create global variables and set their values
Dim gsUserName, glUserID
gsUserName = Request.QueryString("UserName")
glUserID = CLng(Request.QueryString("UserID"))
Main()

'------------------------------------------------
' Purpose: This is the main segment of the page. Here we
'   call the various functions
' Parms: None
' Returns: None
'------------------------------------------------
Sub Main()
  ' Say hello to the user
  sayHello()
 
  ' Change the user ID and display this to the user
  displayUserID(changeUserID())
End Sub

'---------------------------------------
' Purpose: This routine greets the user
' Parms: None
' Returns: None
'---------------------------------------
Sub sayHello()
  Response.Write("<BR>Hello, " & gsUserName & ". Welcome to the test page!")
End Sub

'-----------------------------------------------------
' Purpose: This function changes the user ID. Itjust adds
'   100 to the current ID and returns it. It uses
'   the global variable glUserID and uses a local variable
'   to hold the temporary result.
' Parms: None
' Returns: The new user ID, long data type
'-----------------------------------------------------
Function changeUserID()
  Dim llUserID llUserID = glUserID + 100
  changeUserID = llUserID
End Function

'-------------------------------------------------
' Purpose: This function displays the user ID. It uses the
'   variable passed as an argument to the function
' Parms:
'   plUserID - ID of the user
' Returns: None
'-------------------------------------------------
Function displayUserID(plUserID)
  Response.Write ("<BR>Your User ID is " & plUserID)
End Function
%>

Type this code into an ASP page, let's say part1.asp. You need to call this page from a browser as

part1.asp?userName=yourname&UserID=100

Summary

• Prefix the variable names with their scope and their data types
• Use meaningful variable names
• Be wary of long names
• Use "Option Explicit"
• Use your conventions consistently