пятница, мая 30, 2008

Хороший стиль 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 и т.п., правила сильно не изменятся.

2 комментария:

mandrew182 комментирует...

А ASDoc как заставить генерить private vars?

Racer комментирует...

Я думаю, выносить в доки приватные свойства не имеет смысла.
Это противоречит самому смыслу приватности. Приватные свойства только для внутреннего пользования класса. Извне к ним нет доступа.
Не нужно открывать другим разработчикам внутренности "черного ящика" - это будет только мешать его использовать. Важен лишь интерфейс класса - его публичные свойства/методы.
А комментировать в коде приватные переменные необходимо - для понимания самого кода. Но это касается уже не использования класса, а его разработки.