Documenting Your Code with Comments

You added quite a bit of functionality to make the tour price calculator application work. You can see the results of this work in all your Web pages. In my copy of tourprice_processor.asp, for example, the XHTML document proper doesn't start until line 47everything above that is ASP scripts! Those using ColdFusion will discover that their XHTML documents start around line 19. For the most part, they have the same scripts that do the same thingsit's just that ColdFusion requires fewer lines of code.

If you scroll through all that code at the top of tourprice.asp and tourprice_processor.asp, you should be able to interpret just about all of the scripts you'll find there (ASP users will have one exception, which I'll get to shortly). You can read these scripts not only because you are beginning to master ASP or ColdFusion scripting, but also because they are fresh in your head. But if you came back in six months, or if someone just handed you this code today for the first time, you might not be able to look at it and know what everything is doing.

This is an important issue, because Web documents have a way of hanging around for yearsoften longer than the developers do. For your own sake, and the sake of your successor, you should document your code, so everyone knows what it's doing.

You document the code using comments, which are pieces of information added to code that tell readers what the code does, but which are ignored by computers interpreting the code. In this final section, you'll go through tourprice.asp and tourprice_processor.asp and comment the code blocks.

Open tourprice.asp. Add a comment just above the query.

In ASP, add a new line below the opening <% at the beginning of the query, and type the following all on one line:
```
[View full width]
' Creates a recordset of all the tour names and IDs from the tbl_tours table in the 
database. This data is used later to populate the form drop-down menu.
```
In ColdFusion, type the following at the top of the document:
```
[View full width]

```
In both languages, comments are denoted in a special way. In ASP's VBScript, you use the single quote (') character. Everything from that character until the end of the line is commented out, or ignored by the interpreter. In ColdFusion, you wrap the comment in special comment tags. In fact, they are the same as HTML comment tags, except they use three dashes instead of two. ColdFusion comments can span multiple lines.

Because these comments are in the language of the server (VBScript or ColdFusion, as opposed to HTML), they are stripped out of the document before it is sent to the client. This means you can document your code as much as you like and not worry about users being able to see it.
Save and close tourprice.asp, and open tourprice_processor.asp.

Most of the scripts used in this application appear in tourprice_processor.
ASP users only: Add a comment to the first significant block of code in the document, as follows.
```
' A small script generated by Dreamweaver to help with the dynamic query
```
Make sure you always add comments in ASP inside the <% %> block.

This script is probably unfamiliar to you, because Dreamweaver added it automatically, when you created the dynamic query (that is, when you filtered the data with the criterion: where tourID = form variable tourName). This comment will remind you what it's doing there and how it got there.

ColdFusion lacks this script, because it handled its functionality in a differentand simplerway.
Find the script that creates the recordset, and add the following comment to it: Queries the database for the tour name, adult price, and child price; data is filtered so that the only record retrieved corresponds to what the user entered in the form.

In ASP, the query script begins with the declaration of its variables: Dim rs_tourprices.

In ColdFusion, the query script is easily identified, because <cfquery> tags surround it.

Don't forget to use the proper comment syntax for your server technology.
Find the form validation script, and add the following comment: Form validation script; redirects user back to tourprice.asp if form fields do not have numeric values.

In ASP, this script begins If Not IsNumeric. In ColdFusion, it begins <cfif Not IsNumeric.
Find the calculation script, and add the following comment: Collects data for number of adults and children, and the prices for both adults and children; multiplies data to calculate total.

After all you've done with this script, you should be able to find it on your own.

When you are finished, don't forget to save and upload these files.