|
Introduction
If you are getting started programming Active Server Pages, there are a few standardized programming practices you can use to make your code more readable. If you are already an advanced Active Server programmer you will probable have many of your own. Programming standards have been common practice in many programming languages for years. However, unlike most things in computer science there is more than one way to format your code, some better then others, and all controversial. We have written down our thoughts on Active Server page standards in the following article.
Use Hungarian notation
Hungarian notation is a standard in defining variables. To use Hungarian notation you add characters to the front of a variable where the characters define the data type. The benefit of using Hungarian notation is that at one glance of the variable, you should be able to interpret both the variables data type and purpose.
For example, suppose you have a variable 'Company'. The variable name of 'Company' can indicate a company name or a company id. You would have to look at how the variable is used or find the definition to know the data type. A better variable name is sCompanyName. The 's' indicates a string of characters and the 'CompanyName' indicates the information contained in the variable. If someone runs across 'sCompanyName' in your Active Server page they will know that it is a string.
This is probably trivial if you are the lone programmer with very little code in your library. Many code bases start out that way. But a successful piece of code will be passed around and be used my many programmers. Hungarian allows the code to be easily transferred and worked on within a group of developers
Common Hungarian Notation in ASP pages
| g_Name |
any global variable |
| sName |
any string of characters |
| iName |
any number |
| cName |
a count of Names (usually used in a looping mechanism) |
| fName |
A Boolean value of TRUE or FALSE |
| oName |
An object |
| cnName |
A database connection |
| rsName |
A result set from the database |
Put Request parameters into variables once
Request parameters are those parameters that are passed from one web page to another in the form of:
http://www.myserver.com/page.html?Param1=XYZ&Param2=45
In the example about the Param1 and Param2 are the request parameters. Every time you retrieve a parameter's value from using the Request object, the request object has to retrieve that value. You should always have a location/function that grabs the parameter values. For example:
<%
sParam1=Request("Param1")
iParam2=Request("Param2")
%>
<HTML>
<BODY>
<%=sParam1%> : <%=iParam2%>
</BODY>
</HTML>
You gain performance by retrieving each variable only once and you know where to look for the code that retrieves that value. Secondly, if you change the param name in the request parameters, you only have to change the retrieval code once. For example, if the new request was:
http://www.myserver.com/page.html?Parm1=XYZ&Parm2=45
You would only have to change your code in one spot like so:
<%
sParam1=Request("Parm1")
iParam2=Request("Parm2")
%>
<HTML>
<BODY>
<%=sParam1%> : <%=iParam2%>
</BODY>
</HTML>
By retrieving it once in a single location, you can manipulate the data in any way that you need. For instance you can convert the data like so:
<%
Dim iParam2 int
sParam1=Request("Parm1")
iParam2=CInt(Request("Parm2"))
%>
<HTML>
<BODY>
<%=sParam1%> : <%=iParam2%>
</BODY>
</HTML>
Or you can remove extra spaces like this:
<%
Dim iParam2 As int
Dim sParam1 As String
sParam1=Trim(Request("Parm1"))
iParam2=CInt(Request("Parm2"))
%>
<HTML>
<BODY>
<%=sParam1%> : <%=iParam2%>
</BODY>
</HTML>
Use Option Explicit
By adding the command:
OPTION EXPLICIT
on the very first Visual Basic line on the page you force a stricter coding style than the default. With Option Explicit specified, the programmer must Dim all variables before using them. This prevents programming errors like the following:
Dim cObject As int
cObjects=0
For Each Object in Collection
cObject=cObjects+1
Next Object
Notice that no matter how many Objects that there are in the collection coming out of the loop cObjects will be zero. This is because the programmer made a mistake and left of the 's' in the increment line. The code would execute without compiler error, however with OPTION EXPLICT set a compiler error would happen.
The trade off is that you have to do more typing, declaring all the variables, but you produce cleaner code.
Put ASP delimiters at the left hand margin unless code is in line
When writing an ASP page, you use the <% and %> delimiters so the ASP compiler knows when to interpret your code versus displaying HTML code. You can mix ASP and HTML in one of two ways (or both at the same time).
Here is an example of a poorly formatted ASP page.
<%%
sub X()
Set RS = oConn.Execute(sQueryText)%>
<table align="left"><tr><td><UL>
<% do while not RS.EOF %>
<LI>
<a href="<%=RS(2)%>"><%=rs(1)%></a>
</li>
<% RS.MoveNext
loop %>
</td></tr></table><%
end sub
%>
Can you easily tell where the ASP code begins and ends?
The first method of incorporating ASP and HTML is to have the programming separate from HTML, using Response.Write to send any HTML scripting to the client. Here is an example.
<%
sVar = Response("Count")
if (sVar = "15Seconds") then
Response.Write "<H1>" & sVar & "</H1>"
end if
%>
The second method is to incorporate ASP code inside the HTML. Here is an example.
<H1><% = sVar %></H1>
When maintaining or debugging ASP pages, it is important to know where the HTML code is built and returned. If you have to scan the code for the delimiters, the process can become tedious. Always put ASP code delimiters to the far-left margin (the first example), unless the ASP code is inline with the HTML (the second example).
A more common example is a looping function that has both ASP code in and out of line with the HTML code. Here is first example again but formatted with the delimiters on the far left margin.
<%
sub X(sQueryText)
Set RS = oConn.Execute(sQueryText)
%>
<table align="left"><tr><td><UL>
<%
do while not RS.EOF
%>
<LI>
<a href="<% =RS(2) %>"><%=rs(1)%></a>
</LI>
<%
RS.MoveNext
loop
%>
</UL></td></tr></table>
<%
end sub
%>
Use Include Files
When programming C or Visual Basic, knowing when to use a procedure to encapsulate code that is used again and again is a distinction that separates good from average programmers. In programming Active Server Pages, include files are the equivalent of procedures. For Example, you have 50 Active Server Pages, which include a meta description for search engines like so:
Example.asp
<HTML>
<HEAD>
<TITLE>Example</TITLE>
<META Name="description" Content="An Example">
</HEAD>
<BODY>
The Example
</BODY>
</HTML>
You realize that you want to change the description after adding the correct line in all 50 pages. Now you have to go through and modify all 50 pages again.
If you had created your pages like this:
Example.asp
<HTML>
<HEAD>
<TITLE>Example</TITLE>
<!--#include virtual="/meta.inc"-->
</HEAD>
<BODY>
The Example
</BODY>
</HTML>
and had created another page called meta.inc like this:
meta.inc
<META Name="description" Content="An Example">
You would only have to change the meta.inc file to change the meta description in all 50 pages.
Sites like 15 Seconds and ActiveServerPages.com rely heavily on include files for quick manipulation.
Some of the things that can be included are:
- Cookie Handling Functions
- Constent Variable declarations
- Footers
- Headers
- Repeated Text
Know when to use a Sub versus a Function
The Function has the ability of taking and returning parameters as well as a return value. A Sub has the ability to taking and returning parameters but does not have a return value.
A function should always be used if any error can happen inside the function. The first example is a routine that takes as a parameter a string of characters. The code inside the routine should check to see it the string of characters is "" or null before any processing. If the string is null then an error via the return value should be thrown.
If the routine requires absolutely no processing of global or local variables, then use a SUB. An example is an SUB that prints out the current date (using the Date() function) in HTML.
HTML comment beginning for ASP debugging
Begin and end every Function or Sub with HTML debugging statements. This way you don't have to comment out any ASP code when you release and the debug code is always available. Here is how this would look in the INC file:
Admin.inc
<%
Function AdminDisplayDeleteForm(g_iContentID,g_sScriptName,sText,sWhatis)
%>
<!-- Admin.AdminDisplayDeleteForm B -->
<%
Response.Write sNewLine
%>
<FORM ACTION="<%=g_sScriptName%>?g_iMode=3&ID=<%=g_iContentID%>" METHOD="POST">
Do you really want to delete the <%=sWhatis%> with a Description of
<br>
<b><%=sText%></b>
<br>
And an ID of
<br>
<b><%=g_iContentID%></b>
<Br>
<INPUT TYPE="SUBMIT" NAME="Button" VALUE="Delete">
</form>
<FORM ACTION="<%=g_sScriptName%>?ID=<%=g_iContentID%>" METHOD="POST">
<INPUT TYPE="SUBMIT" NAME="Button" VALUE="Cancel">
</form>
<!-- Admin.AdminDisplayDeleteForm E -->
<%
Response.Write sNewLine
AdminDisplayDeleteForm = 0
end function
%>
The HTML comments AdminDisplayDeleteForm. The Response.Write sNewline (where sNewline = Chr(10) & Chr(13)) adds a line feed after the comment so the next functions comment appears on the next line.
Leave plenty of white space and tabs
It's very easy to get into the habit of writing code quickly but not so quickly debugged or maintained. The expense of the project will be in maintenance and debugging. By adding white space and tabs to the code, you are ensuring a degree of logic and readability to your code. Most of the code written in this article uses standard practice white space and tabs and should be easy to read. By interweaving HTML and ASP code, it is twice as important to be able to quickly determine if the cause of your problem is due to HTML or ASP code.
Any HTML tags or attributes should be capitalized
When reading your code, you will need to quickly decipher ASP from HTML. Many editing programs will color-code for you. How many times have you been in someone else's office debugging the code? If the HTML were all capitalized, it would be easy to decipher your HTML versus in-line ASP.
Understand the difference between when to use global variables and when to pass variables
Global variables should be any information that is 'global' to the entire application. You may have a routine that always prints the page title (a global variable) in the <H1> tag. As long as that function is used to only print the page title, there is no reason to pass the parameters.
However, assume you have a function that prints out a result set from ADO. This result set can have a different title each time so the title should be passed in as a parameter.
|
