Making My ColdFusion Tags More Consistent

I'm in the middle of writing a detailed Coding Standards/Best Practices document for my company. I'm definitely going to include this information. I've always wondered what the best way to list attributes was - most of the time sticking to alpha, or whatever came to me at the time - but, this makes a lot of sense. Thanks.

So it looks like you're doing subject - indirect object - verb - direct object? I tend more to subject - verb - indirect object - direct object when I code. But as long as you are consistent, that's cool.

My personal pet-peeve is the lack of consistency between YES/NO and TRUE/FALSE for attributes. Drives me crazy. I'm a TRUE/FALSE kind of guy, but I don't really care which it is, just frickin' pick ONE!

I just yesterday finally got around to installing the CF8 taglibs for HomeSite+ and literally the first thing I did was open up the VTM folder and do a global find and replace for YES:TRUE and NO:FALSE.

Except ... wtf is up with imageSetAntiAliasing(img, "on")? Like we needed a third set of options?

I'm not really sure that comparing a function evocation to tags for formatting is really a solid comparison. You can look at them and conclude the opposite reasoning as well. I mean, if you look at the <cfset /> tag, and then converted it to a function, you'd have an evocation that looked like set(x, f(y)). Looking at your file example, the a "translation" of the CF tag to a function call would be FileRead(file, "myfile.txt"). This indicates that your code should list the action first, variable second, and other params after that.

I personally list the variable I'm saving last, because the tag "reads" clearer. <cffile action="read" file="mytext.txt" variable="x"/> reads as "Read mytext.txt into x".

I've finished to keep one simple rule for any attributes/properties in any technology :
- coldfusion tags attributes,
- flex mxml tags attributes,
- OO class properties (as3/java...),
- sql table properties,
...

This simple rule is "alphabetical order"!
It works great, easy to understand and to read for anybody.

Incoming rant...

Does it really matter?

I've never worked at a company where they have even remotely rigid code conventions and I can't imagine ever doing so. Does it really make a difference if I don't always put attributes in the same order for the same tag?

Try implementing something like this with a development team of even only a few developers and you'll probably give the idea up pretty quick. Developers are creative. We all have our own style. In one of my last companies, even without comments I could tell who wrote a particular function just by looking at the style of their code; where they put their braces, how they names their local variables, etc. Why would you want to take that away?!

We're programmers! We're here to be creative and write code, not obsess over the order of attributes, whitespace and variable naming conventions!

Just my €0.02!

George.

@Ben

... that really sums up how I feel about development as well.

Thanks for the moment of zen in my day.

Any fool can write code that a computer can understand. Good programmers write code that humans can understand.
-- Martin Fowler

I'm okay with all of these changes except for you putting trailing slashes on your unclosed CF tags (cfset, cfqueryparam, etc).

It's UTTERLY unnecessary and it just irritates the bejeezus out of me. ColdFusion is NOT HTML code and shouldn't be treated as such.

@andy,

I'm sorry but I have to disagree with you. Not fundamentally, but, for the reason I'll explain below.

For me it is easier to read code that has self-closing stand-alone tags.
So, when I'm looking at:

<cfif someConditions EQ true >
<cfset somevar = 'a value' />
<cfset doSomthingTo(somevar) />
</cfif>

I can see the sets very clearly because they close and the logic constructs like cfloop and cfif because they don't.

It's all personal taste and style right?

That's just one of my 15 pieces of flare. :-)

I have two different pieces of information to add to this, so I'll split my response into two parts.

Part 1:

I have to say that I'm on board with Jon. The tags definitely read better when laid out "verb subject object" style - it more naturally follows the conventions of spoken enlish. The goal of any code should be to read as close to your native spoken language as possible. That makes it much easier to understand if it's not your code, and much easier to maintain if it is.

Think about if you were publicly speaking about your code, or even discussing it with another developer on your team. What sounds more natural - "read the file into the variable", or "take the variable and read the file into it"?

Let's frame it another way - suppose you were to outline your code, or to write pseudo code. What reads more naturally:

if file exists
read file into variable
manipulate variable
save variable to file

Or this:

if file exists
variable is assigned result of reading file
variable is manipulated
variable is saved to file

Now as a disclaimer, if you were writing in some languages (some of the functional ones come to mind), the second form is closer to what you would write in code, and may in fact make more sense to you. But I think we can all agree that the first version generally reads easier.

What is more important to the logical flow in the abstract, high-level sense - the fact that a file is being read, or the fact that a variable is being used?

---------------

Part 2:

If you still disagree, just head to the source itself - the CF documentation. If you read the docs, you will see that the tags generally follow the format suggested above by Jon and myself. And I don't think that's an accident. Reading from the docs, you generally see this:

CFFILE action=""
CFIMAGE action=""
CFTHREAD action=""
CFFEED action=""

And here's a subtle but important point - most of the tags in CF already have an *implied* action (invoke, execute, output, object, query). These tags generally take the subject of the action as the first attribute. So if you want to remain consistent with those tags, you'd want to maintain "action subject" prhasing. Examples:

CFOBJECT component=""
CFEXECUTE name=""
CFINVOKE component=""
CFOUTPUT query=""

Also, if you think about it logically, for the tags that require an action parameter, the action parameter really denotes a separate logical operation. For example, cffile action="read" has different attributes entirely than cffile action="write". And I'm betting that under the covers in the CF source, each action is logically separated into either its own function, or into it's own block-level operation.

Let's do a really extreme contrived example(tm) just to illustrate a point. What if the CF designers had decided to just lump all of these into one tag instead. These could be written like so:

CFFOO action="object" component=""
CFFOO action="execute" name=""
CFFOO action="invoke" component=""
CFFOO action="output" query=""

What's more important here, the first paramter or the second? Which parameter controls the behavior of the tag, and thus has different logical meaning?

@Chris...

The thing is though, with well formed code, the two cfset lines would be indented, PLUS you already know that cfset is a single line tag. So while your concept might be sound, your specific example is not.

Anyway...it IS a matter of personal preference, but it just doesn't make sense.

@Ben

You touch on the "non-important" attributes being at the tail end of the tag. This is an important thing to note, and is kind of the point I was trying to get at. This is especially important to consider in the tags that we are talking about. All of the tags that have the action="" attribute have different sets of required and optional attribtues depending on the action being performed.

The entire *meaning* of the tag changes based on the value of the action attribute. Thus cffile action="write" and cffile action="read" have entirely different meanings. You can't separate the action from meaning and indeed from the operation of the tag, and you shouldn't.

In your response, you used cfinvoke as an example.

... What IF, all I showed you was this:

cfinvoke returnvariable="" .... /

What would you feel? Would you be totally lost?

Of course not, but that's because cfinvoke has an *implied* action. You simply don't need to specify the verb. Cfinvoke implies that you'll be calling a function or an external object and retrieving a result.

Let's look at a tag that requires an action though - cfimage. To borrow from your example, what if all I showed you was this:

cfimage name="img"

Would you be totally lost? I'm betting you would. What did that cfimage tag *do*? Did it read it from disk? Did it add a border? Did it resize? Who knows. There's simply no way of knowing without the context of the action.

To put it another way, the tag itself is really "cfimage action=read", not just cfimage. Cfimage has zero meaning without its action attribute, and the two should not be separated because of this. The action is clearly the most important aspect of the tag.

And that's exactly my point - the fact that CF is storing the image in the variable isn't at all important. What CF is doing to the image *before* it stores it in the variable is the important part. The action that's being performed *is* the logical flow of your code. The variable name has nothing to do with that. You could easily change the name of the variable and have absolutely zero impact to what your code does. But if you change the action, the entire operation of your code changes.

Sorry - hit reply too soon.

What I'm getting at is that cffile or cffimage in and of themselves do *not* in fact imply that anything is occurring and cannot be separated from their actions.

Getting back to your earlier examples with functions, of course I would not write this code:

ListFind( list, value ) => returnVariable

I would obviously write:

returnVariable = ListFind( list, value )

But look at the name of your function. ListFind - you have encoded the name of the tag *and* the action into the function name. So of course it makes sense that if you were to convert it to a tag, it would be written: "cflist action=find", precisely because that is equivalent in phrasing to ListFind.

That's why cffile action="read" is written FileRead and cffile action="write" is written FileWrite as functions.

By your logic, would you write it like this:

List returnvariable Find(list, value)?

That's equivalent to what you're doing the way you're writing tags in the blog post.

First off, I want to say that I'm very much enjoying this debate - I think there are great points on both sides, and that it's a great thought exercise. :)

Before I answer the cfset question, let me try one last tack to see if it better explains where I'm coming from on this. Some of my habits are admittedly so ingrained that it's been difficult to characterize why I'm defending them. But I think now I have a beter explanation than I've had so far.

So my day to day is actually only about half ColdFusion. I use a ton of .NET, and before that Java, and before that C++. I have used all of these in the context of integrating other systems and technologies with CF. So from day one with CF, I've also used a ton of other langauges, most of them supporting some level of object orientation or class library. (As a side note, the .NET integration in CF is the best thing that ever happened to me, but that's a different story...)

I don't consider cffile to be an "operation" as I think you do. You see cffile, and you think "hey - we're doing a file operation". When I see cffile, I see a class library. Just because there is a cffile tag doesn't mean that an operation is implied. So when I see cffile, it looks more to me like a class or an object would. So in my head, this is cffile:

class cffile
public any read(string filePath)
public void write(string filePath, any value)
public void copy(string filePath, string destination)
public array readBinary(string filePath, integer length)

This is how I see cfimage:

class cfimage
public struct info(string filePath)
public image read(string filePath)
public image resize(image originalImage)

So when I see a cffile tag, what I really see in my head is this:

cffile.read(filePath)
cffile.write(filePath, data)

To me, the "action" attribute is the function, and the tag itself is really just a class library or an object. As such, they are inseperable. They cannot be separated, or they lose all of their functionality, and indeed all of their context.

Now on to cfset ....

Given the above, there are two ways to look at this. First off, if you look at it as I have framed it from a library standpoint, then you have two options for returning a value. You either return a value, or you update a buffer or an out parameter.

If we're approaching it from the standpoint of most closely matching the way the tags are writen, you would pass in a variable to handle your result, or use a buffer.

In C++, I would think of that something like this:

class cffile
public void read(string filePath, string* output)

(This would be a byref value in .NET instead of a pointer)

When you call it, you would pass in a buffer to hold the results. So your code would basically look like this:

string* output
cffile.read(filePath, output)
print(output)

This is the way that I think most closely models the way that tags work. They don't really have the concept of return values - you give them the name of a buffer in which to store your result. But the important part here is that the action, or the function, is still not separate from the class.

The other way to look at it is as if the operation is using return values. In this case, it would look like this:

class cffile
public string read(string filePath)

In your code you would use it like this:

output = cffile.read(filePath)

Note that the function is still attached to the object even though we're using left-hand assignment for the result. So still, cffile and the action or function (read) still need to be written together.

I think that what's important in this operation is the order of evaluation. The right-hand side is evaluated first. So the order of evaluation is still: perform the operations on the right-hand side, and then do something with the result. Just becuse the target of the assignment is on the left side, this does not make the assignment the more important operation. The operation that is evaluated first, and is thus the more imporant of the operations is still on the right-hand of the operator.

Now to directly answer your question about cfset . . . I think you answered it already in your example. Storing the result is an optional operation. Therefore, the "name" or the result parameter is an optional parameter. That means that it has lower precedence. To me, that means that it belongs last in the list of attributes. So yes, if I were designing cfset, it would look like this:

<cfset value="#Bar()#" name="Foo" />

Whew - that was a lot of typing after 2 beers. I hope that what I wrote made sense :)

Couldn't be bothered reading all the comments :p
But nice post Roland - I think that pretty much covers it imo

@George Bridgeman,

I'm with George. We get paid to write code not to sit around and have some sort of academic circle jerk meets totalitarian S & M over _EXACTLY_ how the code looks (I'd find tamer words but that would seem to be bit of disservice when posting a comment at Kinky Solutions).

When we look at how much man of us are getting paid, one has to wonder how getting hung up on something as unimportant as attribute order is worth an extra $100 here or there just to get things sorted out exactly per some some standard. Exactly what is gained by an extra, let's say, $250 dollar a month being spent making sure attributes exist in some specific order?

I would argue absolutely nothing of value is generated. Someone feels good they did something "productive" by making sure it was part of some best standards and some others get to grumble about how bob or cynthia keep writing code that doesn't follow the best standards. But nothing comes from it that is actually add value for the customer.

I know, I know... some folks will say it's easier than maintain. Really? You're telling me that women and men that can tackle working with complex CF applications are somehow slowed down because the name attribute didn't come first in a tag. Like "oh crap, I've used the cfinput tag before but hell if I know how it works with the name attribute is listed 4th".

Now we all have our preferences. And sure it's nice to be consistent. I used to think it was a big deal to have best practices that included things like this in them. Maybe I've hit my head one too many times but these days it feels a bit like a bunch of teetotalers forcing through prohibition. No matter how well intentioned it is, it will never actually work. And it forces a specific view point on others, one that is essentially subjective.

After all, if having perfectly uniform code produced value why aren't we all using a fancy code beautifier to fix up all are ColdFusion code? Surely after what? 12-13 years of CF if it was so valuable to do we'd have a tool to it with.

This topic surprised me. I simply do thing in [TYPE][Alphabetical Order].

For example: In a CSS file, I will group all classes together and list them in alphabetical order. Inside a ColdFusion tag, the grouping is not required so the attributes are listing in alphabetical order.

Simple and logical (at least I think so).

Can you give me an example of "subject - verb - indirect object - direct object", I am not sure I follow.

Yeah, I agree 100% with the true/false stuff. I believe with the GetAsBinary, you actually need to use Yes cause its not just yes and no, I think you can select Auto. But that being said, I started using true / false where ever possible the second it came out.

Well, let me stop and reiterate definitions for each of those grammatical terms.

Subject: The focus of the sentence.
Verb: The action of the sentence.
Indirect Object: The thing upon which the subject and verb are acting.
Direct Object: The recipient of the action performed on the Indirect Object; "to whom" or "for whom".

Different tags have different connotations. Some are implicitly verbs, such as cfset, while others are implicitly subjects, such as cffile. However, Ben's post was primarily about the latter case, so that's what I was referring to:

Subject: tag name, such as cffile.
Verb: action attribute - what do you want me to do with the subject?
Indirect Object: file or source or similar attribute - what's the action acting with or on?
Direct Object: variable or destination or similar attribute - where do the results of the action end up?

English is generally: subject, verb, direct object, indirect object.

"[Rick] [posted] [a comment] on [Ben's blog]."

So, if we were to follow that same order in tags:

But, it's just as valid to go: subject, verb, indirect object, direct object. This is often use to eliminate prepositions.

"[Rick] [sent] [Ben] [an email]."

In this case in CF tags, you'd swap the last two attributes (file and variable).

Personally, I try to code more toward the latter case (IO then DO) as when I come back through the code later the IO is almost always the more important thing -- that is, where the result went is more important than what went into making it.

But that's just me.

Ack, Ben, can you unboldify that last comment? Sorry about that!

The problem with cfset is that there are only 3 of the 4 components. You can think of it as either an implied verb or an implied noun:

<cfset y=x>

translates as:

"cfset [stored] y from x" -- implied verb
or
"[cfset] set y from x" -- implied subject

Admittedly, the second seems like a bit of a redundant stretch, but it keeps more with the previous theme of the tag being the subject, such as cffile.

So, knowing that, we're left with IO and DO. The DO is the thing upon which the subject/verb/tag acts, while the IO is the recipient of that action.

I think the tricky thing here is that you want to think of cfset as performing its function on the left side, right? But that's not the case -- all of the action really happens on the right and the left side is just a byproduct.

Hence why you can do <cfset foo()>, which might translate as "[cfset] [ran] [the function foo]" -- Subj-Verb-DO. You can't have an IO without a DO, and you can't have a left side without a right side. But you can have a right side without a left side and a DO without an IO.

So ... the right hand side is the DO, as that's where all the action happens, and the left-hand side is the IO, as that's the recipient of the action.

So, yes, cfset is Subj-IO-DO.

(And keeping with my point above, the IO or recipient is more interesting than what goes into it, and is thus on the left and foremost visually.)