Maryland ColdFusion Users Group

CF Style Guide

September 12, 2000

By Eron Cohen and Michael Smith

 

At the Maryland Cold Fusion Users Group meeting on September 12, 2000, a group discussion was held on important style implementations. The idea was how to reduce the number of bugs and to make code maintenance easier. A side-benefit is that in programming teams the code is fast to be understood by new coders. A lot of the ideas are to do with making the code look a certain way so that if there is an error it will stand out from the clean pattern of "correct" code. The following is a compendium of the tips and ideas put forth by the group. Please email us if you have any more of your own.

 

• Indentation: Use indentation to make your code easier to read. That is move in one tab when you start an open tag such as <CFIF> or <CFLOOP> and move back when the tag closes at </CFIF> or </CFLOOP>  You can use CodeSweeper to help you with this.  (See below for information about CodeSweeper)

• CodeSweeper is built into ColdFusion studio and is represented by the  icon on the toolbar.  This feature is very useful because it uses standards settings to allow you to homogenize all of your code. Eg upper case all tags, indent CFIFs etc. You can even customize to your own standards. Be careful not to use CodeSweeper on certain kinds of items such as CFMAIL and HTML tables because indentations can throw off the formatting of the message.

 

• Commenting Use commenting to make it easier to understand what you’ve done at a later time: 

 

1.      Put a standard comment at the top of each CFM template to let people know what the page does, who wrote it and when.  Leave a space for modifications and change history.  For Custom tags, put an extra comment at the top letting everyone know what the input and output parameters are.

2.      Comment blocks or sections of code so that it's easy to tell what each piece does. No point in commenting every line.

3.      When using embedded loops make sure you put a comment at the top of each one to let people know what is supposed to happen there.

4.      If you need to comment out a block of code, put the date the comment was created and why that block of code was commented out.

 

·        Variable Naming Name your variables consistently with capitalization or lower case letters.  Do not use abbreviations for words in your variable names.  Make sure your variable names are descriptive as to what they actually do.  Avoid "hijacking" variable names and reusing them for a purpose they were not meant for.  When naming form fields, use the same names as the fields in the database that they correspond to. Follow the same rules for database tables and fields. Descriptive names make a lot of code self-documenting

 

·        File Naming  Name your files descriptively. No T.CFM but use TestMainForm.CFM instead. Use standard naming prefixes to help simplify identifying a files purpose.  For example, in the fusebox methodology they use dsp_ to name a file that will display something, act_ to represent a file that takes some action or updates a database table and qry_ to represent a file that contains a SELECT query.  Make sure the rest of the name of the file is sensible and corresponds to what the file actually does.  Avoid abbreviations. For non-cfm files, use other prefixes such as P to represent a picture, R for scanned Resume etc.  Always use the .CFM extension for your files.  Although it is possible to use other extensions, it makes it harder to identify a file and edit it with ColdFusion studio.

 

·        Scope all of your variables.  Not only will it speed up your code and make it easier to debug, it will also help guard your application against cross-site scripting.    For instance, for a form variable use the FORM. Prefix. Other scopes include url., application., session., client., variables., request., server., cookie. and attributes.

 

·        Use as few # signs as possible Many developers overuse pound signs in their ColdFusion code.  For the most part, you only need pound signs when you’re actually outputting information in the HTML.

 

·        Keep your pages of code short Make sure your blocks of ColdFusion code stay on one screen.  This means both horizontally and vertically.  Try not to use WORD WRAP in ColdFusion studio so that you can keep the indentation of your code consistent.  You may want to consider using CFINCLUDES or CFMODULE to streamline the structure of your code and to make it more modular -- even if the included code is only used once in your application.

 

·        Keep your code simple Wherever possible opt for simpler code to accomplish your task.  Simpler code is easier to debug. We all like to show off new tags and programming tricks but this is the kind of code that really mean bugs can breed in!