Существуют ли неэстетические различия, которые следует учитывать между методами подсказок при написании на CFScript?

Question

Мне известны два метода написания подсказок кода в CFScript.Я хотел бы знать, есть ли какие-либо функциональные, неэстетичные различия между ними и то, что считается наилучшей практикой.

В первой технике, которую я видел, используются комментарии над объявлением функции для добавления подсказок:*

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

Хотя второй метод включает подсказки в самом объявлении:

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

Есть ли причины использовать один, а не другой?Меняется ли ваш подход, если у вас есть аргументы, чтобы объявить, что вы можете намекнуть?

Answer 1

Первый стиль, стиль JavaDoc, выглядит немного чище, но у меня есть огромный недостаток:

Комментарии никогда не должны изменять способ выполнения кода. КОГДА-ЛИБО. Вот почему они называются комментариями!

Именно поэтому я предпочитаю второй стиль, даже если он не такой чистый.

Answer 2

Нет никакой функциональной разницы между использованием стиля аннотации / ** * / и встроенным.Кроме того, это не просто подсказки - любые атрибуты могут быть размещены в аннотации или в строке.Насколько я знаю, это чисто эстетический выбор.

Чтобы уточнить:

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

Функционально будет делать то же самое, что и

public function foo() output='false' returntype='query' {} 

Answer 3

Использование getComponentMetaData() атрибутов имеет приоритет над комментариями.В противном случае нет никакой технической разницы.Документация Adobe по компонентам cfscript действительно хороша в этой теме.

Я думаю, что использование комментариев - это лучший способ сообщить о намерениях читателям, потому что он стоит отдельно от кода, которому он предшествует.Принимая во внимание, что атрибуты лучше использовать для применения настройки (например, подсказки для ORM), потому что она помещает эту информацию в соответствие с другим кодом.