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

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

ASDoc

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

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

/**
* @private
* The backing variable for the property.
*/
private var _someProp:Foo;

/**
* Place all comments for the property with the getter which is defined first.
* Comments should cover both get and set behavior as appropriate.
*/
public function get someProp():Foo
{
...
}

/**
* @private
*/
public function set someProp(value:Foo):void
{
...
}

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

можно:

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

нельзя:

/**
* Comments for someProp
*/
[Bindable("somePropChanged")]

public function get someProp():Foo

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

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

Заключение

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