Maryland ColdFusion Users Group
CF Style Guide
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
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
Comment blocks or sections of code so that it's easy to tell
what each piece does. No point in commenting every line.
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.
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
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!