Listing 13.7. An example of a global constant declaration.

<script language="VBScript">
<!--
    Dim s_sngSALES_TAX ' CONSTANT Sales Tax Rate
    Dim s_sngCOUNTRY_A_CONVERSION_RATE ' CONSTANT for the conversion rate for
                                       '   cou ntry A to be applied to the dollar

    ' Set up values for variable constants which should not be changed anywhere
    s_sngSALES_TAX = 0.04 'CONSTANT initialization
    s_sngCOUNTRY_A_CONVERSION_RATE = 1.56 'CONSTANT initialization

The sng prefix tells you that this constant contains a single data subtype representation rather than an integer. It becomes a very easy matter to understand where a constant is and what it represents if you declare your constants in this manner. Consider the following code:

vCurrentSale = iItemPrice * s_sngSALES_TAX
vConvertedDollars = intCurrentDollars *s_COUNTRY_A_CONVERSION_RATE

If you follow the constant conventions recommended here, the use of constants will jump out at you as it does in the previous code segment. Several things are clear at a glance in this code. It uses constants that are global in scope. You even know the type of the constants. This type of consistent approach to using constants will make maintaining your code much easier for the same reasons that the variable convention pays off.

A Convention for Intrinsic Constants

Some necessary constant values are dictated by the VBScript language itself. For example, a certain value is expected for the second parameter of the VBScript MsgBox function to cause it to display yes/no buttons. A different value is expected to cause it to display OK. For example, you can use vbYesNo to request a message box with yes and no buttons, as detailed on Day 14, "Working with Documents and User Interface Functions." The Visual Basic 4.0 language automatically defines these values as a special kind of constant called an intrinsic constant. No declarations are needed to use these constants. The constants start with a vb prefix to indicate they are values expected by Visual Basic, such as vbOkOnly.

VBScript does not provide such automatically defined intrinsic constants in the current beta version. However, you can declare your own intrinsic constants as needed by using variable declarations, as shown on Day 14. For this type of constant, it is recommended that you use the same vb prefix naming convention used by Visual Basic 4.0. When you reference intrinsic constants in code, you should use the approach defined by Microsoft for the intrinsic constants. Intrinsic constants start with a lowercase vb and then use mixed case for the remainder of the name. For intrinsic constants, the vb prefix indicates that this is a Visual Basic intrinsic constant, and the mixed case improves readability.

This serves a couple purposes. It helps you distinguish which constant values are required by the language (vb prefix names) versus which constant values are defined by you for your own constant purposes (all-uppercase constant names). Also, if VBScript does add support for automatically defined intrinsic vb constants in the future, you can simply remove your declaration statements and your code will already take advantage of the expected names. And if you ever need to port code between VBScript and VBA or Visual Basic, the porting will go more smoothly if you have used the same constant names supported in those other environments. A file of such vb constant declarations is available on the CD-ROM that accompanies this guide under \shared\tools\constants.txt. These declarations are compatible with the values required by the VBScript language and use the same names as the automatically defined constants of Visual Basic 4.0, so you can be assured of maximum future compatibility. You can double-click on this file to bring it up in Notepad or another text editor, and then copy and paste the declarations you need into your VBScript code.

Objects

Now you have seen details about standards and conventions for referencing variables. Other elements that your code will frequently reference are objects. Day 10, "An Introduction to Objects and ActiveX Controls," looks at how to insert objects such as controls into your Web page and then reference those from your code. That lesson describes how you can name an object through its ID attribute. The name that you specify as the ID is the name you use in code when referring to the object. You have also seen many different types of ActiveX control objects, including text boxes, timers, new item controls, and many, many more. On Day 18, "Advanced User Interface and Browser Object Techniques," you will find out about many more host environment objects automatically defined by the browser. What if you use many of these objects on one page? How do you keep them straight in your code statements? The answer, of course, is more conventions!

The good news is that the approach for objects is very similar to that of variables. Descriptive names are essential. In many cases, it might be helpful to use two words to describe an object; one is the descriptor and one is the noun. You don't need to indicate whether an object is global in scope because every object declared through the object tag is global by definition. Likewise, all the automatically declared browser objects you will learn about on Day 18 are global in scope. As a result, you don't need to worry about the s_ prefix. You do need to worry about an object type prefix. Objects come in a variety of types, and you indicate that an entity is an object and the kind of object it is through the prefix. Table 13.2 shows the prefixes you can use for some of the more commonly encountered objects.

These prefixes provide descriptive, meaningful names for your objects. You should give the objects descriptive names that are combined with their prefixes. Notice that the names for some objects, such as the command button object, should be descriptive of an action, as in cmdCalculate. Other objects that contain user-supplied information but are not directly associated with an action, such as a text box control, should have descriptive names similar to those of variables, as in txtShoeSize. You should make your own customized object-naming convention list a part of your standards because this is one part of your standards in particular that is likely to evolve. Over time, more and more controls of various types will probably become part of your programming repertoire as more controls become available. You will want to expand your standards to make sure to include standard prefixes for any controls you purchase in the future for your development.

Table 13.2 includes the subhead "Prefix," but the definitions include those for intrinsic HTML elements that are automatically defined, such as text box and check box controls, in addition to those that you explicitly define with the objects tag. These are a special type of object, and conceptually, your code treats them the same.

The obj tag is a generic tag that can be used to refer to any object. There is a virtually unlimited number of types of objects that you may encounter. Each new control created by vendors is a new kind of object. You may find that if you try to come up with a new meaningful prefix for each control you use, your code soon becomes filled with variable prefixes that confuse and befuddle you rather than serve the intended purpose of clarifying your code! For that reason, it is a good strategy to prefix the many objects under the spectrum that aren't addressed in Table 13.2 as obj. If you couple that with a meaningful name, then at a glance you can tell everything you need to know about the identifier. You know from the prefix that it's an object, and you know what kind of object from the remainder of the name. This can encompass ActiveX controls; browser objects such as windows, documents, frames, and the navigator; Java applets; and more. On the other hand, if you use one specific type of object frequently, it may warrant designating a standard prefix for it to help it stand out in your code. Remember, the overall goal is that you want prefix payback without prefix clutter!

Good naming conventions for objects are just as important as-and in some instances, more important than-naming conventions in other areas. This is because you can declare objects in many different places throughout a script. Keeping them straight can become a bit of a maintenance challenge as your Web pages grow larger. If you use good naming conventions, you have immediate feedback about exactly which types of objects the code is using and whether they are implicit or explicitly declared. Consider the following line where neither prefixes nor descriptive names are used in referring to an object:

feedback="normal"

This statement doesn't tell you too much without additional digging. A little dose of conventions makes it more descriptive even without looking further into the source code:

lblHeartRateFeedback.caption="normal"

This line tells you that a label object is used and provides more details on the type of information displayed in that label. Just the application of standard naming conventions to this statement is enough to tell you that the line fills a label with heart rate feedback. The modified statement also illustrates that object names, just like variable names, use a mixture of uppercase and lowercase for clarity and reading. The appropriate use of conventions in referencing objects can contribute a lot to the clarity of your overall script.

Procedure Declarations

By now you've seen many illustrations of how clear documentation and a consistent approach pay off. These same benefits hold true for procedure declarations as well. Several different areas of procedure conventions are important.

Descriptive Names for Procedures

Once again, descriptive names are the first step to a good, consistent approach. Because procedures carry out some action, the descriptive names have a slightly different focus. Procedure names should begin with an action word. If you saw a code statement that made a call to a procedure named GPA, it might not mean that much to you. Even if you realized that GPA stands for grade point average, you don't know whether this procedure displays a student's grade point average or prompts them for it or performs some other activity.

A better name for the procedure can make its intent very clear. It is no surprise that a procedure named CalculateGPA calculates a student's grade point average. This is one of the standard areas that you should never bypass. If a procedure does not start with an action word, the description name is generally not adequate. Procedure names, like variable names, should appear in mixed case to improve readability of the word components that make up the name.

Prefixes for Procedures

Prefixes indicating data subtypes of return codes are not generally used for procedures, although in some cases, this could add further clarity. Declaring functions with the appropriate prefix of the type of data that they are to return makes those function names even more descriptive. Because a programmer commonly refers to function description comments when reviewing function call statements, good comments usually suffice.

Procedure Comments

A procedure declaration should have a comment line that summarizes in one brief sentence the purpose of that procedure. There should also be a comment line that describes any arguments whose purpose is not immediately obvious from the arguments' names. Then you should have a line that specifically describes return values from the function if this is a function type procedure. It is important to document the return value for error conditions as well as normal conditions when appropriate. Following these comment lines should appear another descriptive block of comments for procedures that are of substantial size or complexity. The description area explains in detail the logic or algorithm of the procedure.

When writing these comments, the programmer should keep in mind that the reader of the comments will already know VBScript. You should make this assumption when writing comments to avoid unnecessarily over-commenting or adding comments of little value. For example, you don't need to describe the manner in which a For…Next loop works just because a For…Next loop appears within the algorithm. You have to make some basic assumptions about the programming level of the reader; otherwise, you would end up writing a guide like this with each program!

Although the intrinsic VBScript syntax is a well-defined, finite topic that you can expect the comment reader to understand, control usage is not. There is no limit in sight to the number of controls that might evolve, and you shouldn't assume that your comment reader is aware of anything other than the basic ActiveX controls such as those covered in this guide. Although it is a good hunch to assume that your reader knows VBScript, it is not a safe hunch to assume that your reader knows the usage of every control that your code references. If your code uses an ActiveX control, the reader of your comments and code might not be familiar with that control's functionality, properties, or methods. For that matter, if you are making a change to your script a year after it was written, you might not remember the characteristics of a control if it is one you don't use very frequently.

For this reason, it is appropriate to document in your comments any special uses of a control within the script. Descriptive comments are perhaps more subjective than any other standards area. A brief, well-done description can save time over the code maintenance life of a script. However, a poorly thought-out description or a few lines of description that you provide just for the sake of complying with a standard are often of little value. The best standard for the description area is to provide a description that illuminates the reader's understanding of the source code where necessary and appropriate.

Good Procedure Conventions in Action

Following good standards is a combination of using descriptive variable and procedure names and using comments. A script with very good names and a few appropriately placed comments by key declarations can be much more maintainable than a script with poor names and many lines of poorly composed comments. The best standard for procedures is to use descriptive names and start them with an action word in every case. Always include at least a one-line comment with the procedure declaration that briefly describes what it does. If the procedure has arguments or returns a value, include lines that outline that. Then include additional lines that describe the purpose, if needed. If you follow these guidelines, readers of your code will have a good feel for the capabilities of a procedure just by glancing at the top of a procedure declaration. They can dig deeper into the code when needed, but they won't be forced to dig through and decipher a procedure when they simply want to get a feel for what it does.

Listing 13.8 shows a good procedure declaration.

Listing 13.8. A procedure declaration that conforms to standards.

Function CalculateGPA(intGrade1,intCredits1,intGrade2,intCredits2)
'Purpose: Calculates grade point average for a two class-load term based on
'    the student's grade and credit hours for each of the classes
'Arguments:
'    intGrade1,intGrade2 - integer grades for class 1 and class 2 of
'        the student. These will be 4 for A, 3 for B, 2 for C, 1 for D, 0 for E
'    intCredits1, intCredits2 - the number of credit hours for each of the classes,
'         ranging from 1 to 3 hours
'Returns: student's grade point average in single subtype ranging from 0 to 4
'Description:
'    Calculates the grade point average based on the average grade earned per
'    credit hour. Each class's grade is weighted by the number of credit hours
'    for that class to derive an overall average GPA for the student.

Within Your Code

You've seen how to use good conventions for variable names, constants, objects, and procedures. All that's left is the code itself! Most of the steps you can take to write good, maintainable, consistent code have already been described in terms of the other areas. Comments are critical. The same guidelines for procedure comments apply to code in general. Brief comments should accompany any block of code whose purpose is not obvious by the syntax and variable names. Again, the purpose of your comments should not be to explain VBScript. It should be to explain the nature of the problem, the reasoning and algorithms of the code, and the use of any unconventional controls.

There is no set guideline that works in every case for the number of comments required to describe your code statements. Generally, a comment for every line is overkill; but with complex code, this might be appropriate. The best approach is to use a brief comment for a group of statements that serve a common purpose. The placement of comments can help make your code more or less readable, too. Code statements are generally not as readable if comments appear at the end of a statement line. Comments nestled among code statements tend to stand out much better when they appear on a line of their own.

Using white space is another technique that can improve the readability of your code. Using white space simply means inserting a blank line in your code to separate one conceptual block of code from another. This makes each related group of statements stand out more as a separate entity. Some standard recommendations downplay white space for the sake of keeping the overall lines in a Web page as small as possible. It's true that each line of white space increases the overall number of bytes in the script, but the additional overhead from good use of white space is negligible. The maintainability advantages of good white space far outweigh the disadvantages.

Another technique to make code more readable is using proper indentation. We've used indentation throughout the samples in this guide. Good indentation consists of spacing over statements that are logically subservient to a high-level statement. For example, in an If…Then conditional, the statements inside the conditional are only performed if the condition is true. Indenting those statements four additional spaces makes it clear that the If statement always gets evaluated and the indented statements only get executed in certain conditions. Typically, you use four spaces for each level of indentation. Comments that follow a procedure declaration are usually indented one space from the procedure name.

You should also write VBScript syntax keywords consistently. The standard approach is to used mixed case. If…Then is more readable than if…then. The purpose of standards is to enhance the clarity and readability of code. You can use development tools for this purpose as well. Some commercial code editors can, with some effort on the part of the user, be custom configured to highlight VBScript keywords in a given color, and with time you can expect more and more VBScript-targeted tools to emerge in this category. Tools such as Microsoft's Control Pad Editor, described in Day 2, "The Essence of VBScript," also can lead to better code through features like the VBScript Wizard, which provides some automatic code generation. Such tools go a step beyond standards because it's not an action you can control in the way you write programs. However, it is important to realize that to some extent, standards and code viewing and generation tools are aimed at the same purpose-making the maintenance of code easier and more efficient.

A good standard approach for your code statements like that described here is essential. This area in particular pays off when you're writing programs for the first time as well as when they're maintained in the future. If the program is easy to read, it will be easier to spot bugs and improve your logic as you write and work with the code. If the program is hard to read, it will tend to mask bugs and obscure your logic as you compose the program. Notice the code in Listing 13.9.

Listing 13.9. An example of code that was not written according to standards.

if intQuantity < 5 then
msgbox "additional $10 shipping charge will be applied for low volume order"
intOrderSurcharges=intOrderSurcharges+10
end if
if blnPromotionalOrder <> vbTrue then
msgbox "$20 handling fee will be applied"
intCharges=intCharges+20
end if
intTotalPrice = intCostOfOrder + intCharges
intTotalCost = intTotalCost * sngYEN_CONVERSION_FACTOR

You can see from the preceding code segment that it takes a little bit of strain and digging to understand what the code does. Now take a look at the readability when a good dose of standards has been applied in Listing 13.10.

Listing 13.10. Code that has been written with good adherence to standards.

'calculate the low volume order surcharge if needed
If intQuantity < 5 Then
    msgbox "additional $10 shipping charge will be applied for low volume order"
    intOrderSurcharges = intOrderSurcharges + 10
End If

'Add the standard handling fee unless it is a promotional order
If blnPromotionalOrder <> vbTrue Then
    msbbox "$20 handling fee will be applied"
    intCharges = intCharges + 20
End If

'Now calculate total price in yen using item cost computed earlierÂ
plus surcharges
intTotalPrice = intCostOfOrder + intCharges
intTotalCost = intTotalCost * sngYEN_CONVERSION_FACTOR

You can see that it is much easier to read the second segment than it is to read the first. Unless you have a real penchant for puzzling other programmers as well as yourself, the second approach is clearly the recommended one.

Script Structure

A few guidelines pertain to overall script structure. An overview comment should appear at the start of the script. After the script tag <SCRIPT>, an HTML comment should appear on the next line. The use of the HTML comment indicator was discussed on Day 3, "Extending the Power of Web Pages with VBScript." This tag (<!--) should start a script so that browsers that don't support VBScript will treat the whole VBScript as a comment and not display it on screen. The corresponding ending tag (-->) then appears at the end of your script to terminate this comment behavior for browsers that do not support VBScript. Immediately after the comment tag at the start of the script should come an overview comment that states the overall purpose and goals of the script. It might seem to you that the goals of the script would be obvious, but if your page is large, it might not be immediately obvious to a reader who is trying to sift through the entire page. Code can be associated with many different aspects of a page and more than one script can appear in a page, so it is important to describe exactly what purpose a specific script serves.

Generally, your code should appear at the bottom of your page right before the </BODY> end-of-body tag. There are several advantages to this approach. This makes it very easy to locate all the code in a page. And there are some situations, particularly dealing with VBScript code intended to run as the page loads, in which the code must appear after the objects it references. Placing code at the bottom of the script frees you from any such concerns.

You can insert multiple scripts in your Web page. When possible, you should use one script rather than multiple script sections throughout the page. Using multiple scripts makes it that much harder to understand and maintain the code. In most cases, there is no reason not to combine multiple scripts into one script. One of the reasons that multiple scripts are sometimes used is that you can set up scripts to handle specific events, as in the line that follows:

<SCRIPT Language="VBScript" event=OnClick FOR=cmdButtonName>

This dedicates the entire script to that event, as was described on Day 7, "Building a Home for Your Code." If you have more than one event to catch, you'll need more than one script with this approach. However, you can easily convert such an event to a subroutine within one main script. The same event that is handled in a separate script can be converted to a subroutine that is named as follows:

<SCRIPT LANGUAGE="VBScript">
Sub_cmdButton_OnClick

The name assigned to the subroutine will cause it to be called as the event handler for the OnClick event of the button cmdButton. Using this approach, you can group all your event procedures in one script. A quiz solution at the end of today's lesson illustrates this approach.

You can also associate code with other input controls themselves, right on the input control definition line. This technique was addressed on Day 8, "Intrinsic HTML Form Controls." This line calls a message box right from the input control tag:

<INPUT TYPE="Button" NAME="cmdMyButton" LANGUAGE="VBScript"
  OnClick="msgbox 'VB Rules': msgbox 'And it is fun!'">

Similarly, this line calls code directly from the body tag:

<BODY LANGUAGE="VBScript" OnLoad="msgbox 'VB Rules': msgbox
  'And it is fun!'">

In general, avoid the temptation to blend code directly with input control definitions or other elements like this. The more you can group code together in one consolidated script block, the easier your maintenance will be. The code in the input control example above with the input button could be replaced by a subroutine named cmdMyButton_OnClick in the main script body, and the input tag could simply read

<INPUT TYPE="Button" NAME="cmdMyButton">

The code in the body tag example could simply be moved to the main script and placed at the start of the script, before the procedure definitions. Then it would get called at the end of the page load and the body statement could simply read

<BODY>

In both of these cases, you avoid tangling up code with your HTML statements, spread across your page. Instead, you consolidate the code into one well-defined place in your page-the script section. You've laid the groundwork for pages that are much easier to understand, debug, and modify in the future.

Startup code itself warrants some special consideration. Any code in your script that is not in a procedure is executed when it is sequentially encountered as the page loads. As a result, it is very important to know what and where this startup code is. Typically, you should include it right at the start of the script, explicitly commented with a line that says Startup code. But rather than have a large block of startup code, it is better practice to just have one statement that calls a StartUp subroutine you define. The name can be anything you define, but it is important to use the same name consistently across your pages for easiest maintenance, and StartUp is recommended for consistency across the industry (or at least across the pages of readers of this guide!). This StartUp subroutine then becomes the well-known place for any page initialization code, consistent from page to page and project to project.

A previous example from today illustrates that you can associated startup code directly in the body tag. This opens the door to the possibility of calling the StartUp subroutine there, with a statement such as

<BODY LANGUAGE="VBScript" OnLoad="StartUp">

This works as well, but in some respects, it is a much less maintainable approach. If your startup code is clearly designated at the top of your script section, it is perfectly clear when you look at the code what startup code gets executed. If you use the practice of triggering your startup code from the body tag, on the other hand, a reader could review the script statements and never realize that some routine there had special startup characteristics. So the <BODY OnLoad=> approach to indicating a starting procedure can be slightly less clear. If you do use that approach, make sure to use ample comments in the script to indicate the startup behavior caused by the body tag.

Concerns

You have heard a lot of reasons for using standards and conventions. If you've talked to many other programmers or thought much about these issues, you might also have some concerns about the disadvantages of adherence to standards and conventions. Several concerns often come up in relation to standards.

Myth: The Overhead Penalty Outweighs the Advantages of Standards

One of these concerns is quite unique to the nature of VBScript-whether you should avoid using white space and plenty of comments because it makes the Web page size larger. Most programming languages are compiled into a final executable and the end user pays no price for size of the source code. However, in the case of VBScript used with Web pages, the end user is affected. If you put many hundreds of lines of comment into the script on a Web page, the end user will have to download a Web page that is many hundreds of lines larger.

Should this make you avoid comments? The answer is no. The advantages of writing good code through comments far outweigh the disadvantages of this overhead penalty. The extra download time caused by including additional bytes of the script to download will usually be negligible and not something your user will perceive. It would take many lines of comments to add up to the several kilobytes of data that would be necessary to introduce a noticeable wait even on systems connected by the slowest of means. On the other hand, you don't want to turn the comments for your scripts into gargantuan guides to every aspect of a project.

You should keep in mind the download overhead factor and avoid the temptation to add unnecessary fluff or extensive documentation to scripts. If you feel that a lot of documentation is needed to supplement a script, it might be better addressed in a separate design document you could maintain elsewhere. Many projects use a design document approach to document overall goals for a project. Then the developers proceed to build the specific programs or scripts, including only comments relative to that specific script in the script itself. This is a good approach for larger projects and can cut down on extensive comments within the scripts without sacrificing the advantages of documentation.

Myth: Standards Slow Me Down

Another common concern about standards and conventions is that it takes more time to write code when you must worry about making it adhere to standards. This argument is based on a shortsighted view. If you put careful thought into following a good set of standards and conventions and carefully documenting your code through good comments and procedure and variable names, it might indeed take you longer to type in the keystrokes of your program. When this time penalty is compared to the significant maintenance, debug, and even design time benefits that result from good documentation, the truth becomes clear. Carefully adhering to standards and conventions saves time over the long run.

Trying to bypass standards and conventions is a lot like trying to speed up your vacation trip by skipping the visit to the gas station. You'll get on the road more quickly, but you're more likely to run into delay before you reach your final destination when you run out of gas. A good way to make sure that the time taken to comply with standards is productive is to keep in mind that the purpose of your standards and conventions is to increase efficiency overall. If one of your standards seems particularly troubling and time-consuming, you should examine it with respect to your overall standards. If you don't see the benefit of a certain standard, don't use it, but carefully weigh the pros and cons before making such a decision.

The Non-Myth: Standards Constrain Me!

Finally, perhaps the most common concern about standards is that they require discipline on the part of the developer and can make the developer feel constrained. This is no myth but is the cold hard truth, and it is true for good reason. Discipline and constraint is not always a bad thing. Producing software is a creative art, but it is also a logical science. It is something that affects other people and sometimes businesses and their bottom line. Although it might be more fun to program free-form with no thought for the future, it is not the best programming practice.

Paying the price of a slightly more disciplined and constrained approach is well worth the effort. This is especially true because the benefits of following standards and conventions don't mean any loss of creativity or flexibility in design. You just exercise your creativity under more controlled circumstances. The graffiti artist who plies his trade by recklessly defacing buildings has no more claim on creativity than the professional artist who sketches within the borders of a notepad. The professional artist simply has more foresight. The benefits are there for the taking for whoever is wise enough to apply them.

Summary

Today's lesson discusses many aspects of standards and conventions and points out the advantages to using standards and conventions. Code that conforms to a common set of conventions will be easier to maintain, easier to debug, and even easier to write. Often, the act of writing good code as you go along leads you to clearer organization and structure. One of the challenges for getting started with standards and conventions is deciding exactly which standards to use. A good general recommendation is to follow the Microsoft guidelines as closely as possible, extending them where you feel it is necessary for the sake of your project. Today's lesson presents a detailed set of such guidelines.

The lesson first introduces the standards for variables. One important aspect of declaring variables is giving them meaningful, descriptive names with an adjective as part of the name, where appropriate. You should name variables in mixed case to enhance readability. You should also use prefixes with variables, where appropriate, to indicate the intended data subtype representation of the variable. However, this technique is a bit harder to apply in VBScript than in other languages because VBScript is not a strongly typed language. As a result, an important part of the standard approach for VBScript is to use the v prefix to indicate a variable is a variant with a subtype that might change representation. You should use a scope prefix that consists of s_ to indicate global variables that can be referenced from any procedure.

Comments can help a great deal in highlighting the purpose of variables. You can use comments at the end of a variable declaration on the same line as the Dim statement. You can also use them to describe a group of related variables. Such related variables should be grouped together, and any relationships between the variables should be described in the declaration comments. Such comments are provided in a line or group of lines preceding the variables.

Today's lesson also examines constants. VBScript constants are really variables but can still be indicated separately by using uppercase letters for the constant names. Intrinsic VBScript constants are not defined by the user and will always be preceded by a vb. Object names should be similar to variable names. You should use mixed case for readability. You should also use descriptive prefixes to indicate the type of the object. For example, an intrinsic text box control would have a name that starts with txt. An ActiveX control object such as a timer would have a name that starts with tmr. In this manner, the type of object is easily apparent from looking at the source code.

It's also important to provide a standard approach in procedure declarations. Like variable and object names, procedure names should be descriptive. However, procedure names should start with an action type word to indicate the action performed when the procedure is called. It is important to use comments in a procedure declaration, including at least one line that briefly describes what the procedure does. If it's appropriate, you should provide additional lines describing arguments and return codes. If the procedure is not trivial, you can provide additional lines of description in the procedure comment area at the top of the procedure. In any comments, it is safe to assume that the reader knows VBScript. Comments should elaborate on aspects of algorithm, logic, or infrequently used control aspects.

The guidelines for code statements are much the same as those for procedures. You should use good comments, which can refer to groups of statements where appropriate. You should also use indentation and blank lines to set apart code statements and make them clearly readable where needed. Show VBScript keywords in mixed case. Some utilities can also help with the maintainability of code by highlighting keywords in certain colors.

Finally, today's lesson addresses some concerns about following standards and conventions. It is true that to a certain extent, adhering to the conventions listed here can result in larger Web pages. The source code for your scripts will grow larger through the comments and as a result, so will your Web pages. However, in most cases, this additional overhead is very insignificant. It's also true that following conventions might take a little more time in the short run to initially write your programs. This time is more than saved by the improvements in development, debugging, and code maintenance that come about through the use of the conventions. It's also true that using conventions makes you or some of the programmers you work with feel constrained. This is another price that is worth paying if you care about efficient software development and developing the best program possible.

The benefits of standards and conventions are clear and overwhelming in the software industry. Good style and use of conventions pays off in many ways. For example, the use of good, descriptive variable names and procedure names often makes the code very readable in itself and lessens the need for many lines of comments. A more readable program can end up producing many benefits. Code can be easier to debug, maintain, and even originally design. As a result, the end product you provide on the Web for the user of your Web pages and scripts is better.

Q&A

Workshop

View the sample scripts from Microsoft on the World Wide Web. Take a look at their standards and conventions. (You can find all this information at http://www.microsoft.com/vbscript.) Document your own standards and conventions based on what you see there, what you've read today, and what you feel is appropriate. Document an approach that is good for you and your workplace. In what areas do you deviate from Microsoft and this guide? Do you think the industry standard approach will be similar?

Quiz

1. Observe the following program. Its purpose is to accept an age and present one message if the age indicates that the user is in Generation X. Otherwise, it will present a different message. If the age is invalid or hasn't been supplied yet, the user should receive appropriate feedback. Take the following segment and change the variable names and indentation to make it more readable.
2. nm = info.value
   If IsNumeric(nm) then
   if nm < x then
   msgbox "Dude, prepare to surf!"
   else
   msgbox "Welcome - Prepare to enter our Web page"
   End if
   Elsif nm = "unknown" then
   msgbox="you must supply an age to proceed"
   Else
   msgbox "please supply a valid age"
   End if
3. Take the following two scripts and merge them into one script:

<script Language="VBScript" FOR="lblFeedback" event=click>
msgbox "Feedback label has been clicked"
</script>

...asp definitions appear here...

<script Language="VBS" FOR=cmdCalculate"event=OnClick>
msgbox "Button has been clicked"
</script>