DL1t's blog

Несмотря на то, что ActionScript 3.0 является строго типизированным языком, в системе типов имеются некоторые “дыры” (обусловленные наличием типа Function и отсутствием дженериков (кроме Vector во Flash Player 10)), которые, с одной стороны, повышают гибкость языка, но с другой - делают код менее читаемым. В проектах, где число классов составляет несколько сотен и выше, это начинает составлять определенную проблему, особенно в случае командной разработки.

В случае массивов стандарт документирования имеется официально:

var myArray:Array/*of String*/;

Эта форма также поддерживается FlashDevelop (при ее использовании получаем автокомплит для элементов массива, что удобно). Кроме того, для mxml во Flex имеется метатег ArrayElementType, однако в чистых AS3 проектах без использования mxml он все равно не работает.

Однако массивами дело далеко не исчерпывается: для комфортной работы с кодом требуется информация о типах для Responder-ов, коллекций, в некоторых случаях  - информации о точном контракте у Function и т. п. В соответствии с этим при написании кода я проставляю дополнительные типы комментариев, характеризующих типы данных.

1) Коллекции, Dictionary

var features:ArrayCollection/*<String>*/;

var settings:Dictionary/*<String,XML>*/;

Для случая коллекций использование of выглядит неоправданным, так как массив и коллекция являются различными сущностями. Описание же в стиле дженериков Java выглядит очевидно, а также логично, в свете появления Vector с использующим угловые скобки синтаксисом.

2) тип Function

var mouseDownHandler:Function/*MouseEvent->void*/;

Функциональный тип описан по аналогии с haXe, где описание функций более полноценно. Для функций с одним входным аргументом такой вариант выглядит предельно логично, для случая нескольких входных аргументов вопрос усложняется (однако случаи, когда приходится подробно специфицировать функции с несколькими аргументами относительно редки). В этом случае можно следовать описанию типов в haXe (все аргументы и возвращаемый тип разделяются стрелками), либо использовать что-то свое. Вариант haXe для 2-3 аргументов все еще читаем, а в случае большего числа уже логичнее выносить описание функции в отдельный раздел в asDoc, так как inline комментарий станет слишком длинным, вне зависимости от используемого синтаксиса описания.

3) Уточнение типа

override public function doSomething(arg1:Object/*(MyType)*/,arg2:int):void{…}

В некоторых случаях приходится использовать в контракте функции более общий тип, несмотря на то, что в любом случае передаются объекты совершенно определенного типа. Такая ситуация часто возникает, например, когда производится override методов библиотеки, не подлежащей/не поддающейся изменению. В этом случае дополнительный комментарий позволит разработчику быстрее ориентироваться в коде.

4) Responder-ы

var sqlResponder:Responder/*<SQLResult->void,SQLError->void>*/;

Прямое следствие пунктов 1-2. Подобное описание responder-а позволяет избежать использования типа Object для обработки результатов выполнения асинхронных задач, что делает код более четким и читаемым.

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