Bamboozled by Pound Sign Decisions
If you want to greatly vex the Muse and his merry band of developers, all you have to do is send them sample code with a liberal sprinkling of superfluous pound signs and cfoutputs. ColdFusion is a very forgiving language, so you are free to do all sorts of nails-on-the-chalkboard things that make me cringe - and you will get away with it too. I began thinking about this topic because I'm privileged in my current work to review code created by others. This is double edged sword of course. It's easy to sit back and be cheeky about someone else's approach when you are in the "expert" seat. Still, I have recently reviewed code from more than 10 different developers. I've come to the conclusion that many (perhaps most) sort of guess at when to use pound signs. Once they figure out the approaches that work they stick with that.
The result is that pound signs are like Tribbles on the star trek enterprise. They are fairly innocuous but they annoying show up everywhere. So... having never seen a definitive post on the topic I thought I would jump in and put my stamp on when to use and when not to use pound signs. That's right; the Muse is not making room for other opinions this time. I'm going to lay down the law! So put your seat belts on 'cause it's going to be a bumpy ride.
The Output Buffer
So the first thing to know is that there are conditions that always require pound signs. To understand this let me introduce you to the concept of the "output buffer". I've not heard a lot of folks talk about this and there may be other monikers for it, but the Muse has adopted "output buffer" so that's what we are going with. Consider the following dialogue between ColdFusion and your request.
- Request: Yo CF I have some stuff to execute here.
- CF: All right let me create a little memory space to return to the web server. Let's see... type string buffer, yada yada yada.... ok, ready to go.
- Request:Ok... first we got some html stuff and html, header and body tag. Oh... and script tag that references an external JS file.
- CF: JavaScript file... hehe... oh you crazy kid. Ok, let me throw all that into my buffer. What's next.
- Request [checking clipboard]: Let's see.... ok now he wants to run this query - select * from users. Got that?
- CF: Yeah yeah I got it keep your threads on. [whispers to DB driver] ... ok, you are all set. I have the query.
- Request: Cool. Ok now we have a couple of table rows, then a cfoutput, then he outputs a bunch of columns from the DB into a table.
- CF: Got it. Anything else?
- Request: standard stuff... closing table tags, disclaimer and end tags. That about wraps it up.
- CF: Okey dokey. Here's a reference to your output buffer. Get this packed up and back to the browser.
- Request: Will do. take care - I'll see in you a few miliseconds.
- CF: Yeah... and don't forget - we have a party at the maintenance window at 2:00 am. I hear Britney the JDBC driver is showing off her new build.
- Request: I wouldn't miss it for the world....
This silly little dialogue illustrates the old "output buffer" idea. ColdFusion assumes by default that your request will result in output. It's a web server platform after all. So each request starts with an empty buffer. As things happen in a request the content of the buffer is populated with the results of your work.
It may not be obvious at first, but you can manage this buffer. If you have good code separation where you do all your component calls and heavy lifting first you can bracket your controller code like this:
<cfinclude template="myController.cfm"
<cfsetting enablecfoutputonly="no"/>
The Always Rule
Now that I have you thinking about the output buffer let's get back to our pound signs. Here's my first rule:
The Never Rule
The Wrong Way
<cfset blah = #form.blah#/>
</cfif>
The Right Way
<cfset blah = form.blah/>
</cfif>
The Query Rule
...
</cfloop>
<Cfoutput query="qry">
...
</Cfoutput>
<cfmail query="qry">
...
</cfmail>
The Loop Rule
CFLOOP is one of those areas where pound signs don't feel like they should be needed, but in fact they usually are. Take arrays as an example. You can't do Array="arrLoop". Instead you have to do Array="#arrLoop#". Collections (used for objects or structs) suffer the same fate. Doing Collection="MyCollection" is incorrect. Instead you have to do Collection="#myCollection#". I'm sure this probably has to do with by reference / by value type decision making under the hood.
The Concatenation Rule
Ok.. the muse will give some leeway here. When I concatenate a string with variables I tend to do the following:
The Usually Rule
CFSWITCH: When using cfswitch the "expression" is expecting a primitive value (a string, number, etc) for comparison. So it needs the contents of the variable - not the variable name or reference. So this would be correct:
...
</cfswitch>
...
</cfswitch>
CFMAIL: Another example, Cfmail, requires pound signs around variables except for query (see the Query Rule). This leads to an odd result when working with a query. The name of the query is not bracketed by pound signs while columns from the query must be bracketed. This makes sense if you think of a query driven cfmail as version of a query driven cfoutput. So this would NOT be correct:
...
</cfmail>
...
</cfmail>
So again the variables passed into a tag need pound signs. Look at it closely and you can see why. The "From" and "To" attributes also take a string. How is the tag to discern that a string is a column name? The only way it could would be to force the "to" and "from" address in a query driven cfmail tag to be required to be a column - and of course that would severely limit the use of the tag. Other tags like Cfchart, cfftp, cfschedule, cfzip, cffile etc - all require pound signs when a variable is passed in.
Conclusion
I guess if I had something I would like folks to get out of this post it is to stop using pound signs "when in doubt". Now Muse readers, feel free to set me straight, but let's keep those comments clean and civil.
10 Comments
-
If you call the hash symbol (as in #hashtag) a pound sign, what do you call the £ sign? -
@ville,
Oddly enough we ALSO call that a pound sign (or at least I do). The thing is, we rarely have occasion to use the British pound sign. Sorry... I know that's a snooty American answer :)
-Mark -
Hey Muse! Good post, I touched on this a little in one of my CFML 101 posts (http://www.cfgears.com/index.cfm/2009/12/6/CFML-10...)
My general rule of thumb is, the only time I use pound signs ("#", "number sign", "hash symbol", "octothorp", etc...) is if I'm actually displaying a variable's value on the screen, or the variable is in quotes (like in a tag attribute). -
@Eric,
Thanks... that's a good way of thinking about it. I've never heard "octothorp" though. I'll have to add that to my vocab list :) -
> like in a tag attribute
Yes, that one has confused me at times.
I've had to use argumentCollection="#form#" instead of argumentCollection=form. -
Good post Mark. Good to know about whitespace stuff. I saw that on some sites and I always thought where is that coming from. lol @ driver, new build. :-)
You mentioned, you do code reviews. Well in that case, check out this link http://wtfcode.net/ . It seems its all about wtf/minute that says everything about code.
I read a similar post but directed towards the *excess usage* of cfoutput, like how you should use it only when you really want to output something or dont open and close cfoutput for every single thing. Rather just use one cfoutput and close it when you have included all that you want to display as output. Ben forta had said it, here is the link I found
http://www.forta.com/cf/resources/tipstricks_files... -
Wondering what the general feeling is when something like the following is encountered:
cfmail to=#email# from=#email# ...
What's with the missing quotes? I won't lie... it bugs me to no end. Mostly from readability and consistency perspectives. CF seems to be okay with it so I know the practice will continue. -
@brad,
I agree that inside of a "service" tag like cfmail or cfhttp or cfchart that quotes are the norm.
-Mark -
With JavaScript being case sensitive, I'm starting to grow accustomed to dotting every i and dashing every t.
jQuery, you had me $('.
Sites to Watch
Aggregators
RSS
