Macromedia Coldfusion MX 7 Web Application Construction Kit

The last thing to plan before you start coding is how you will continue to document the project as you go along. After all, if you've worked to create all those great flowcharts and other design documents, it would be silly to not keep them up to date while you work.

Charting Page Flow

One of the most valuable things to have at any time is an up-to-date list of important pages and the links between them. Dreamweaver MX can help you with this by letting you organize your application files maintaining links between all the templates in your project (see Chapter 2, "Introducing Macromedia Dreamweaver MX"). But sometimes there's just no replacement for a proper paper document (perhaps a Visio drawing) that you can keep pegged to your wall for reference.

If you keep your page-flow document up to date throughout, you'll have that much more to refer to if you need to make adjustments to the application a year from now. And let's not forget that clients and bosses always like to see documents with recent dates on them, no matter what's actually in the documents.

Include Files and Custom Tags

Another handy document to keep current while you work is a list of include files and custom tags. You learned about include files in Chapter 9, "CFML Basics," and you will learn about custom tags in Chapter 23, "Building Reusable Components." Although both types of files are handy because they enable you to isolate and reuse your code, it can be easy to forget which files rely on which other files. A simple spreadsheet or document that keeps track of these interdependencies can really help.

Commenting Style

Throughout this book, we encourage you to comment your code as much as possible. Any code, ColdFusion or otherwise, is a hundred times more valuable if it is thoroughly commented. And it becomes a thousand times more valuable if all the code for an application is commented in a consistent style.

You should decide ahead of time how you will comment your code, and stick to it while you work. For instance, you might make resolutions like these:

• Each .cfm file should have a header comment that lists the purpose of the file, when it was first written, and the original author's name.

• When anyone makes a significant change to the file, the header comment should be amended, explaining which portions were added or changed. Over time, you'll develop a detailed revision history for each file.

• The header comment should list the variables used within the template and what they are for. If the file is a custom tag, each attribute should be listed and explained.

• Each significant change or addition to a file should be noted in place with an explanation, date, and the developer's initials.

• There should be at least one line of comment before each CFML tagperhaps a few exceptions can be made for self-explanatory tags such as <CFOUTPUT>, however.

Naming Conventions

Some developers are strict about naming conventionsfor very good reason. We're not going to suggest any specific sets of naming conventions here because different people have different ideas about what makes sense. It's something you and your team should decide for yourselves.

That said, here are a few ideas:

• Because short variable names can result in cryptic-looking code, you might require that every variable name consist of at least two words, with the first letter of each word in uppercase. So instead of variable names such as tot and fn, you would have names such as CurrentTotal and FirstName.

• Many coders like to use the first letter of each variable's name to suggest the type of information the variable will hold. For example, you could use sFirstName and sShipAddress instead of FirstName and ShipAddress to instantly see that the actual values will be strings. Similarly, you might use dFirstVisit for dates and nCurrentPrice or iProductsOrdered for numbers. You also could use similar naming conventions for the columns in your database tables.

• Similarly, some people find that having the names of their database tables start with a t or tbl, such as tCustomers or tblCustomers, is useful. Sometimes people also choose to come up with a convention to indicate the relationship between related tables, such as calling a table tCustomers_Orders or rCustomers2Orders if the table relates rows from the tCustomers and tOrders tables.

• Some developers like to put all forms into a separate include file and start the filename with frm, as in frmNewUser.cfm or perhaps frm_NewUser.cfm. Other people do something similar with each <cfquery> tag, ending up with files with names such as qryGetDirectors and so on. See Chapter 38, "Development Frameworks," for more information.

Keeping the Directory Structure in Mind

There are no hard and fast rules about how to organize your ColdFusion templates and other files into folders, but you should put some real thought into it and come up with a scheme that makes sense to you.

Here are some things to keep in mind:

• Make every effort to keep the directory structure of your application as organized as possible. For instance, it often makes sense to have a folder that corresponds to each high-level section of the site (the sections that appear on your main navigation bar, or the sections accessible from the application's home page).

• Folders are like friends. Unless they are too full of themselves, the more you have, the better. It is almost always better to have lots of directories with relatively few files in them, rather than a few directories with hundreds of files in each.

• Decide where your images and other media files will be kept. For instance, this book calls for keeping them all in a single folder named images. You might decide to maintain a number of subfolders within images. Of course, you could also decide to use an entirely different strategy, perhaps keeping your image files in the same folders as the templates that use them. Just choose a method and stick with it.

• In general, it is most convenient to use long, descriptive filenames. However, if you will be displaying a link to a particular template many, many times on a page (for each record in a database, say), a long filename might add to the size of the final HTML code your template generates. Try to use somewhat shorter filenames for templates that will be linked to extremely often. The same goes for images that will be included in pages frequently.

TIP

The Yahoo! site is a good place to look for an example of a site that uses a very sensible, hierarchical URL structure, but where each portion of the URL is kept very short (often just a letter or two).

Moving Targets and Feature Creep

Unless you are particularly blessed by the gods of application development, you will deal with the twin evils of Moving Targets and Feature Creep. These scorned, ugly creatures are sometimes so filthy and wretched as to be barely distinguishable from one another. Moving Targets, of course, are those aspects of an application that your client keeps changing their mind about from one day to the next. Feature Creep is what happens if little extra features keep getting piled onto the application while you work. Either one will keep you from getting your project done on time.

On the other hand, it's only natural that the best suggestions and most exciting "Eureka!" moments will come while the application is being built. Development is a creative process, and you or others might stumble upon a really brilliant idea that must be in there. Therefore, you should plan on making a few concessions or adjustments during the development process. Have some type of agreement in place about how to deal with incoming ideas.