Are there non-aesthetic differences to consider between hinting techniques when writing in CFScript?

Question

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?

Answer 1

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.