Entries for month: June 2010

Sometimes Hate Isn't A Strong Enough Word...

While things that I hate about ColdFusion are relatively few and far between, they do exist. After all, as Jeff Atwood says in StackOverflow podcast #73, you don't really know a programming language until you can think of 5 things you hate about it. I wouldn't be "FusionGrokker" if I didn't know the language through-and-through. This may be a topic I revisit later when other things bug me, but for now, I'll just focus on the one that's driving me up the wall today.

Let's talk about JavaDoc-style comments in ColdFusion, and how they affect code execution. First of all, I'm not making any claims about performance. My only interest here is that comments are affecting attributes. Even if using this notation quadrupled performance I would still be against it.

Here's some sample code (from Dan Vega):

/**
  * @displayname Product Service
  * @hint I am the service layer for Product objects
  * @output false
  * @extends AbstractService
  */
component {}

Any sane programmer looks at that, and translates it, in her brain, to be equivalent to this:

//@displayname Product Service
//@hint I am the service layer for Product objects
//@output false
//@extends AbstractService
component {}

"Oh how thoughtful!" she might think. "The original developer left nice tidy notes about this component for me." But therein lies the problem: It is not the same! Those comments are not comments. Here there be dragons.

If we convert the same code into its tag-based equivalent, then we can see the difference plain as day. The first code block is equivalent to this tag-based code:

<cfcomponent 
    displayname="Product Service"
    hint="I am the service layer for Product objects"
    output="false"
    extends="AbstractService">
</cfcomponent>

While the second block is equivalent to this tag-based code:

<!---
  @displayname Product Service
  @hint I am the service layer for Product objects
  @output false
  @extends AbstractService
--->
<cfcomponent></cfcomponent>

This behavior is documented, albeit somewhat poorly, on pages 117-120 of the CF9 Developers Guide (PDF).

No other programming language does this. Comments are meant for the benefit of the developer, not the compiler. If you read the Wikipedia page on programming comments, you'll primarily notice two things: a line about comments "augmenting" code to make it more readable for programmers, and several mentions of other things being done with comments, like documentation generation and integration with source code management systems. And for the record, I'm entirely in favor of these things.

But back my point: Comments clearly should not change the way a program runs. This is madness! And in my opinion, it must stop. It must be removed post-haste. And I am not alone in this line of thinking. Both Ben Nadel and Dan Vega have posts up discussing the new syntax, and in the comments on both posts several people express basically the same opinion. (And for what it's worth, the syntax does seem to garner a supporter or two, too.)

Now, you may have noticed that the JavaDoc syntax requires a slight modification to the comment syntax. As Dan pointed out in his post, this code did not alter the attributes of the component:

/*
 * @displayname Product Service
 * @hint I am the service layer for Product objects
 * @output false
 * @extends AbstractService
 */
component {}

But by changing /* to /** (as in my first code block in this post) all of a sudden it did what he was expecting. That's a significantly subtle difference. What if out of the blue HTML5 introduced something like this:

<!---
  @id myDiv
  @class fooClass
--->
<div></div>

Ignore for a moment that it would not be easy to use this syntax with ColdFusion, as that's what a tag-based CF Comment looks like and it wouldn't be sent to the browser. Just think about HTML. It's different. It doesn't use the exact same existing HTML comment syntax, but it looks close enough. Would that be acceptable?

God, I hope not.

Personally, I will continue to write my components in the slightly uglier syntax (it's true!) but that I believe will be much more readable by beginners and experts alike:

component
  displayname="Product Service"
  hint="I am the service layer for Product objects"
  output="false"
  extends="AbstractService"
{}

...And I hope you will too.

Don't get me wrong. I'm all for metadata. I love how it works in Flex. But I don't think Metadata should be encased in comments. To quote a friend, "metadata should use metadata syntax". If you agree with me, I would encourage you to vote for this bug -- hat tip to Nathan Mische for posting it on Dan Vega's entry.

in ColdFusion | 4 Responses Posted 2010-06-04 12:40