QuackFuzed [ Ramblings of a Con..ColdFuzed Mind ]

Learning CF9: Buh Bye Comment-Based Attributes

Posted on December 18, 2009 at 4:32 PM in ColdFusion

In my previous entry I discussed the use of comment-based attributes for the new all-script CFCs in CF9 and what it actually takes to make them work as advertised. As Andy Matthews pointed out in a comment on the post, they aren't technically "comments" in a traditional sense, but rather are JavaDoc notations.

After spending a bit of time weighing the arguments both for and against the use of comments as executable code, and playing with using them and not using them, I have conclusively sided with the "comments as executable code are pure evil" group. Why?

Simply stated, other than the fact that it just doesn't feel right, when I went back and opened up files that I had written with the JavaDoc notation (and had not looked at in a week or two), I noticed that I was taking more time refreshing my memory as to the details of what exactly the code did. My eye would naturally skip over the comments and look at the code. The code appeared incomplete and left me shaking my head going "HUH?!?!"

In other words, the details were lost in the comments. I feel that comments should not contain the details. They should simply be... ummmmm... comments!

On the other hand, details of files that utilized a more traditional attribute declaration were quickly refreshed in my mind. There are, of course, many other arguments against them, but frankly that's good enough for me.

The thing about the standard inline declaration syntax that bothered me was having (potentially) really long lines of code. I detest having to scroll horizontally. So I played around with a number of coding style variations and came up with one that helps me see everything that's going on at a quick glance.

1. public string function (
2. required string value1,
3. string value2="foo"
4. )
5. hint="This is a quick hint"
6. output="false"
7. {
8. // method code here
9. }

Hopefully that helps someone out there who is struggling with horizontal scrolling like I was. :-)

Comments

(Comment Moderation is enabled. Your comment will not appear until approved.)

On 12/18/09 at 5:24 PM, Henry Ho said:

output=false is almost useless unless you're calling cfc in CFML style or you're calling 3rd party code that calls writeOutput() somewhere. Generally, output=false can be skipped.

I agree, "comments as executable code are pure evil", but for hint, I think that's fine. However, hint is still cleanest in /** */ comment block IMO. Just don't put cf-orm/hibernate annotations there, you don't get code insight in CF Builder if you use the comment block way.

On 12/18/09 at 7:20 PM, Dan Vega said:

The great thing is your are not limited to a certain style. I for one love the Java doc syntax and find it much cleaner that the approach you have here. To each his own right! In the end is less verbose that tab based components and thats what makes me happy!

On 12/18/09 at 7:45 PM, Dan Vega said:

As I learned yesterday as well putting extends in java doc won't give you code insight into the super class. I am going to file a bug for both of those though because if it's valid builder should pick it up!

[Add Comment]