четверг, мая 29, 2008

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

Сегодня мы поговорим о том, как правильно организовать структуру файла Flex-фреймворка. Оригинальный текст: File Organization. По этой теме информации пока не много - большая ее часть в разработке.

Структура файла

Порядок организации файла следующий:

  • Блок Copyright
  • Объявление пакета package
  • Список объявлений import
  • Объявление use namespace
  • Метаданные класса
  • Объявление класса class
  • Инициализация класса extends
  • Список объявлений implements
  • Подключение файла Version.as
  • Список констант класса
  • Список "mix-ins"
  • Ресурсы, используемые классом
  • Переменные класса (static)
  • Свойства класса (static)
  • Методы класса (static)
  • Конструктор
  • Переменные
  • Переопределяемые свойства
  • Свойства
  • Переопределяемые методы
  • Методы
  • Переопределяемые обработчики событий
  • Обработчики событий
  • Вспомогательные классы, не входящие в пакет

Блок Copyright

Вставляйте в каждый .as-файл фреймворка блок copyright. Текст open-source copyright '2008 можно посмотреть здесь: Блок Copyright. Ширина блока - 80 символов.

Метаданные класса

Группируйте метаданные в разделы, в следующем порядке:

  • Events
  • Styles
  • Effects
  • Excluded APIs
  • Other Metadata

Вставляйте малый разделитель перед каждым разделом. (О большом и малом разделителях будет написано в следующей главе "Форматирование").

В каждом разделе располагайте метаданные в алфавитном порядке по имени name="...", а в разделе Other Metadata - по имени тега.

Код примера можно посмотреть здесь: Организация метаданных класса.

Подключение файла Version.as

В каждый класс необходимо подключать файл Version.as, содержащий объявление константы с номером версии static const VERSION:String:
include "../core/Version.as";

Список констант класса

Здесь объявляются статические константы static const.
ActionScript 3 не позволяет объявлять константы типов Array и Object. Такие константы необходимо объявлять как static var, но помещать в этот раздел, поскольку по своей сути они являются константами.

Список "mix-ins"

Здесь объявляются любые статические переменные типа Function, которые принимают ссылки на методы, но не объявляются в качестве методов. (Понятие mix-in я раскрыл так, как смог понять - возможно я ошибаюсь).

Свойства класса (static)

Здесь объявляются статические установщики и получатели (getter/setter) класса. Располагайте их в алфавитном порядке по имени свойства. Для каждого, используйте подзаголовок с именем свойства. Объявляйте сначала получатель, затем установщик.

Методы класса (static)

Здесь размещаются статические функции static function.

Переопределяемые свойства

Здесь объявляются переопределяемые нестатические установщики и получатели (getter/setter) класса. Располагайте их в алфавитном порядке по имени свойства. Для каждого, используйте подзаголовок с именем свойства. Объявляйте сначала получатель, затем установщик.

Свойства

Здесь объявляются новые нестатические установщики и получатели (getter/setter) класса. Располагайте их в алфавитном порядке по имени свойства. Для каждого, используйте подзаголовок с именем свойства. Объявляйте сначала получатель, затем установщик.

Переопределяемые методы

Здесь размещаются переопределяемые нестатические функции.

Методы

Здесь размещаются новые нестатические функции.

Переопределяемые обработчики событий

Здесь размещаются переопределяемые обработчики событий.

Обработчики событий

Здесь размещаются новые обработчики событий.

Комментарий

Я изменил порядок следования пунктов, так как они в оригинале расположены в абсурдном порядке:

  • Подключение файла Version.as
  • Список объявлений implements
  • Инициализация класса extends

Порядок в структуре класса очень важен, так как позволяет легче ориентироваться в коде класса. Однако располагать свойства и методы в алфавитном порядке - работа не для слабонервных.

Для оформления класса "в релиз" это конечно важно, но для личного пользования или на этапе разработки, на мой взгляд, лучше сортировать свойства и методы (конечноотдельно друг от друга) по их функциональности, и каждую область озаглавливать общим комментарием. А в конце, иметь утилитку типа ASDoc, которая бы отформатировала код и расставила свойства и методы в алфавитном порядке.

На основании этой статьи уже можно создавать шаблон класса для FlashDevelop, но лучше - после следующей главы "Форматирование": Formatting.


1 комментарий:

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

IMHO удобнее код класса бить на блоки.

У адоба кстати так и есть в некоторых классах.

В этом плане жжет VisualStudio

#region ISomeInterface
.. implementation
#endregion