4

I'm aware of two methods to write code hints in CFScript. I would like to know if there are any functional, non-aesthetic differences between the two, and what's considered best practice.

The first technique I've seen uses comments above the function's declaration to add hints:

/**
* @hint This function does soemthing
*/
public function foo() {}

While the second technique incorporates the hints into the declaration itself:

public function foo() hint="This function does something" {}

Are there reasons to use one and not the other? Does your approach change if you have arguments to declare that you may want to hint?

Mohamad
  • 34,731
  • 32
  • 140
  • 219

3 Answers3

6

The first style, JavaDoc style, is a little cleaner looking, but I have a huge personal gripe against it:

Comments should never alter the way that code runs. EVER. That's why they are called comments!

That is why I prefer the second style, even though it is not as clean looking.

Adam Tuttle
  • 19,505
  • 17
  • 80
  • 113
  • I think you're being a bit dramatic with your font size there, but to each his own ;) – Todd Sharp Jan 06 '11 at 15:22
  • 1
    It's something I'm passionate about. Comments modifying code execution is fundamentally evil. – Adam Tuttle Jan 06 '11 at 15:30
  • Maybe it was a bit over the top. Changed it. :P – Adam Tuttle Jan 06 '11 at 15:31
  • To be fair - it's not a comment, it's an annotation. :) – Todd Sharp Jan 06 '11 at 15:33
  • @Adam, I agree with you. I think it is a bit weird to think that comments can modify code execution... – Mohamad Jan 06 '11 at 15:36
  • @Todd: Sure, it's an annotation. Explain that to the new guy who is wondering why his method is remote-accessible when he doesn't want it to be, and he just hasn't noticed that @access remote is in the comments. – Adam Tuttle Jan 06 '11 at 16:40
  • +1 Adam, I agree completely. Allowing program functionality inside comments was a terrible architectural decision. I could understand basing an automatic *documentation* feature on JavaDoc. That would make sense. But the decision to do it this way has created an ambiguous weak point in the language, and a likely WTF moment for newcomers to the cfml/cfscript world. – Ken Redler Jan 06 '11 at 16:49
2

There is no functional difference that I am aware of between using the annotation style /** */ and inline. Also, it's not just hints - any attributes can be placed in the annotation or inline. As far as I am aware it's purely an aesthetic choice.

To clarify:

/**
*@output false
*@returnType query
*/
public function foo() {}

Will functionally do the same exact thing as 

public function foo() output='false' returntype='query' {}
Todd Sharp
  • 3,207
  • 2
  • 19
  • 27
  • Todd, this is interesting... I thought "public" being the first word of the function declared the "access='public'" -- what's the use of including it in the annotation? – Mohamad Jan 06 '11 at 15:35
  • Ah yes - sorry - that's not necessary. Was just looking at a tag based CFC in my IDE as an example and didn't pay much attention. I'll remove it from the annotation for clarity. – Todd Sharp Jan 06 '11 at 15:41
  • "query" return type should be between to public and function keyword, no need to use returntype= – Henry Jan 06 '11 at 19:26
  • Works either way, but yes, that is a shortcut Henry. My point was simply that attributes can be inline or annotation style. – Todd Sharp Jan 06 '11 at 21:16
  • If we're getting technical I didn't even have to say output='false' because that is implied in cfscript based functions. – Todd Sharp Jan 06 '11 at 21:18
1

Using getComponentMetaData() attributes take precedence over comments. Otherwise there's no technical difference. The Adobe documentation on cfscript components is actually pretty good on this topic.

I think using comments is a better approach to communicate intent to readers because it stands apart from the code that it precedes. Whereas attributes are better used to apply customization (e.g. hinting for an ORM) because it places that information inline with other code.

orangepips
  • 9,891
  • 6
  • 33
  • 57