Хороший стиль Flex-программирования. ASDoc

Немного о комментировании/документировании в стиле ASDoc: ASDoc.

ASDoc

Комментирование свойств

Документируйте только первую функцию пары установщик/получатель (get/set). Пример объявления и документирования свойства:

/**<br>* @private<br>* The backing variable for the property.<br>*/<br>private var _someProp:Foo;<br><br>/**<br>* Place all comments for the property with the getter which is defined first.<br>* Comments should cover both get and set behavior as appropriate.<br>*/<br>public function get someProp():Foo<br>{<br>...<br>}<br><br>/**<br>* @private<br>*/<br>public function set someProp(value:Foo):void<br>{<br>...<br>}

Комментарии ASDoc применимы к тегам метаданных так же как и к другим элементам класса. Поэтому важно, чтобы комментарий относился к правильному элементу. Например, если свойство обозначено тегом Bindable, комментарий должен располагаться непосредственно перед функцией получателя (get), а не над метатегом Bindable:

можно:

<br>[Bindable("somePropChanged")]<br>/**<br>* Comments for someProp<br>*/<br>public function get someProp():Foo<br>

нельзя:

/**<br>* Comments for someProp<br>*/<br>[Bindable("somePropChanged")]<br><br>public function get someProp():Foo<br>

Про документирование ASDoc можно посмотреть подробнее здесь.

PS: Ввиду уродского движка редактирования текста Blogger, местами поехали все пробелы в статье Хороший стиль Flex-программирования. Форматирование. Поэтому, лучше не надеяться на примеры кода, а читать текст.

Заключение

Цикл переводных статей про хороший стиль Flex-программирования еще не закончен. Через некоторое время я вернусь к этим статьям и, возможно, те правила, которые были отмечены автором как TBD будут опубликованы. На сегодня мы имеем достаточно информации, чтобы улучшить свой код. Будем надеяться, что с выходом Flash Player 10, новых SDK и т.п., правила сильно не изменятся.