Macromedia - Writing Maintainable Code

Writing Maintainable Code
By Jeff Bouley
Consultant

Introduction

It is extremely unlikely that the code you write today will stay the same forever. Even if you will rework the code, six-month-old code can look like a foreign language. You can avoid many of the headaches, late nights, and caffeine overload associated with updating code by simply following a few guidelines. This article will examine coding best practices for writing maintainable code, including consistent variable naming conventions, code structure, and comments.

In addition, modularized coding provides maintainability and reusability. Modularized coding involves developing the framework of an application in a way that code can be written once in a particular file and called multiple times in different areas of an application. Rather than rewriting 60 lines of code, the developer writes an open-ended file that can handle an attribute passed to it, or one that was set earlier in the page.

ColdFusion provides a variety of programming conventions to promote modular coding, including custom tags and include files. This article will discuss these items and demonstrate a custom tag example. You can download a ZIP file containing the files referred to in this article by clicking on the link here, or at the end of this article.

•	Consistent Variable Naming Conventions
•	Code Structure
•	Comments
•	Custom Tags or Include Files?
•	Custom Tag Example: State List Select Control
•	Attached Files Instructions

Consistent Variable Naming Conventions

To create maintainable code, use consistent conventions for naming variables. Consistent naming conventions not only help with code creation and debugging but also prove invaluable when you revisit the code. The following group shows a list of suggested variable prefixes.

•	For strings:	`s_VariableName`
•	For booleans:	`b_VariableName`
•	For integers:	`i_VariableName`
•	For structures:	`st_VariableName`

By using these prefixes, you will be able to evaluate, debug, and reuse variables with ease. Also, when someone else needs to work with your code, he will understand the type of value represented by the variable.

Code Structure

Is there a more difficult programming task than fixing another developer's unstructured and undisciplined code? In this scenario, you spend most of your time fixing the previous developer's poor coding format so you can understand the structure of the code.

By simply indenting each level of logic, and matching start and end tag levels, it is easier to navigate long sections of code and identify typos which become more obvious with properly formatted code. Use the following suggestions to make your code easier to read:

•	Indent the SQL one tab from the `cfquery` tag.
•	Combine all fields from the same table together.
•	Break to a new line on a new table's fields.
•	Break to a new line for a new SQL keyword.

Notice below how easy it is to read the code when you follow the guidelines, as in the following example. This example shows a a properly structured cfquery tag:

<cfquery name="GetRecs" Datasource="#DSN#">
  SELECT table1.field1, table1.field2, table1.field3, table1.field4, 
         table2.field5, table2.field6
  FROM table1, table2
  WHERE table1.field1 = table2.field5
</cfquery>

Tables are no exception to proper code structure guidelines. Read the following list for a few suggestions:

•	Match the Table start tag level to the end tag.
•	Match row tags <TR> at the level of the table.
•	Indent cell tags <TD> one level from rows.
•	Match level on all closing tags.
•	Indent nested tables.

Again, this makes each item easier to find and edit. Look at the following code:

<table border="1" width="500">
<tr bgcolor="0000CC">
  <td>Text in the cell
  </td>
  <td>Text in the second cell
  </td>
</tr>
</table>

By definition, the second table would start on the third tab and the table cells on the fourth.

Comments

Comments may be the most important of all steps in writing maintainable code. Even though they have nothing to do with code functionality, comments explicitly state the developer's coding logic. For example, how can a person load a custom tag file and expect to use it if he or she has no idea of its inputs and outputs?

In addition, what about that tricky piece of logic one developer might have labored over for hours? Is it possible to expect the next developer to take one look at it and know what it does and why without comments? It only takes a few simple comment lines to explain the code. It can make or break a project schedule.

At the end of this article, you will find some examples of comment blocks in a ZIP archive for download. Another file will also be in the ZIP archive that can be placed in the C:\Program Files\Macromedia\ColdFusion Studio 5\UserData\Snippets directory (replace the version number for your current version of ColdFusion Studio) and then accessed through the ColdFusion Studio snippets tab in the left side console.

Custom Tags or Include Files?

While they are at the heart of writing maintainable code in ColdFusion, deciding whether to use a custom tag or include files takes a some consideration. If the code needs to perform operations that intermingle with the existing page, such as displaying the header or footer text, displaying navigation links, and returns no modified data, use an include file. If data needs to be manipulated, use a custom tag.

Include files are usually located in a specified directory. Sometimes they are named include, and you can use the ColdFusion Administrator to access them. To protect the include code on your server from hackers, store the directory outside of the webroot directory and encrypt the include files before uploading them. A note of caution: If you decide to encrypt the files, copy them to a special location before running the encryption as a backup option. Otherwise, you may lose the unencrypted copy of the files.

Custom tags are treated similar to include files. They are usually placed in the /cfusion/custom tags directory. It is recommended that you encrypt custom tags before uploading them for security reasons too.

Because custom tags offer the ability to pass data and manipulate it in a protected environment, they are an easy and efficient use of code. Two possible uses for custom tags are described below: one example is quite simple that you can use all the time, and one example is more specialized, and would be used less frequently.

Custom Tag Example: State List Select Control

How often have you seen, used, and created that pesky United States list select control in forms? The code below is an example of how to call a custom tag to display the state list control with just one line of code.

CT_STATESELECT contains a few parameters. Selected by either default or edit, the name of the variable will be created by the control, size of display, and what entry (Postal Code). It outputs the control to the HTML stream but returns no values.

Why bother using a custom tag for easy code like this? Why not just use an include file, or copy it where you need to use it? The answer is simple. You can maintain one custom tag more easily than 10 versions of the code snippet, each in various files, in multiple website projects (folders). When you need to make a change, you only need to update the code in one place by using the following custom tag:

<cf_ct_StateSelect Nam="StateName" Size="1" Val="#GetRec.StateCode#">

Attached Files Instructions

Download the ZIP archive. The ZIP archive contains the files referred to in this article. To use the files, follow the instructions below:

1	comment_header.hse comment_header.hss	Place these files in the C:\Program Files\Macromedia\ColdFusion Studio 5\UserData\Snippets directory.
2	info.cfm	Place this file in the CFUSION/Custom Tags directory.
3	caller.cfm	Place this file under the webroot or somewhere where you can enable browsing on the directory through a virtual mapping in IIS or any other web server.
4	cf_info.vtm	Place this file in the c:\Program Files\Macromedia\Cold Fusion Studio 5\Tag Defs\CFML directory. Open this file and look at the syntax associated with enabling drop down of attributes in ColdFusion Studio.