Flex 最佳做法 - 开发做法

处理资源

Flex 应用程序通常会并入一组文件, 包括图像、CSS 文件、字体、音频剪辑和视频等不同类型的媒体。如果能保持应用程序的资源和源代码井井有条, 之后需要对软件做出更改时就可以节省时间。以下是命名和存储 Flex 应用程序相关文件时应考虑的一些一般指导方针。

创建和使用“assets”目录

常见的最佳做法是创建一个名为“assets”的文件夹, 将它存储在 src 目录中。Flex Builder 在设置 Flex 项目时创建这个 src 目录。

因此, 资源目录根目录的路径是: src/assets

使用 assets 目录中的子目录

为了有助于组织可用于应用程序的各种媒体类型, 建议您根据使用的媒体类型合理组织一些子目录。以下几点强调了子目录的一些常用做法。

使用 SWF 目录

可以考虑将 Flex 应用程序中的 SWF 文件存储在一个名为“SWF”的目录中。您可以根据加载到应用程序中的 SWF 文件的用途使用其它目录。例如, 可以将模块存储在其它目录中。模块超出了本文的讨论范围, 但您可以通过编写模块获得更多信息。

SWF 目录路径是: src/assets/swf

使用 images 目录

将 JPG、GIF 或 PNG 文件等图像资源存储在一个名为“images”的目录中。

图像目录路径是: src/assets/images

使用 fonts 目录

Flex 应用程序可以包含嵌入式字体。将非标准字体用于 Flex 应用程序时, 将 TTF 文件和其它字体文件存储在一个名为“fonts”的目录中。同时请记住, 字体可用性因平台不同而异。包含字体是一个好办法, 尤其是当开发小组在不同的平台上工作时。

字体目录路径是: src/assets/fonts

使用 audio 目录

音频是富 Internet 应用程序中的常用媒体类型。将 MP4 和 WAV 文件等音频资源存储在一个名为“audio”的目录中。

音频目录路径是: src/assets/audio

使用 video 目录

将视频存储在一个名为“video”的目录中

视频目录路径是: src/assets/video

使用 XML 目录

如果应用程序包含 XML 配置文件或不调用服务器而直接加载到应用程序的 XML 文件, 将它们一起存储到一个名为“xml”的目录中。

xml 目录路径是: src/assets/xml

图 1 所示的目录结构说明了这些惯例。

图 1.使用子目录组织资源

 

ActionScript 3.0 编码标准

为应用程序创作源代码时, 可以通过几种做法确保应用程序代码库的条理性和可读性。它们对于之后处理该应用程序的其他开发人员会有所帮助。如果今后需要修改这些代码, 它们也可以帮助您回忆起代码的来龙去脉。

在开发中使用软件包的最佳做法

不要将动词、形容词或副词用于软件包名称

命名软件包时应避免这些词。使用复数或概念名词。

将复数名词用于软件包

包含多个类的软件包的名称应当使用复数, 如“effects”。

根据软件包中的类命名软件包

例如, 如果应用程序包含一组自定按钮类, 则可以为它们创建一个名为“customButtons”的软件包。

有关软件包的更多最佳做法, 请参阅 Flex 最佳做法－第 1 部分: 设置 Flex 项目。有关创建软件包时可考虑的其它做法, 请参阅 Flex SDK 编码惯例和最佳做法*。
类的最佳做法

 将类主体中定义的可执行代码量降最低

将可执行代码嵌入方法中。

 使实例变量与自变量匹配

如果创建了用于接受自变量的构造函数并且它们设置实例变量, 那么应使自变量名称与内部属性名称匹配。

 创建类时使用经典的一般惯例

类名应当是应用程序中独一无二的对象。对象应当有采用 UpperCamelCase (第一个词的首字母, 以及后面每个词的首字母都大写) 格式、基于单数名词的名称。例如, 如果我编写一个在线购物车系统, 我会命名两个类, ShoppingCart.as 和 Customer.as。还应当避免特别大的类。

 将类类型 (formatter、validator、event 和 error) 加在类名称后面

对于 formatter、validator、event 和 error 相关类, 将类类型加在类名称最后。例如, 使用 ServiceConnectionError、ServiceConnectionEvent、ServiceResultsFormatter 和 ContactFormValidator。

 将外观类型加到类名称后面

创建与外观相关的类时, 将类类型加到类名称最后。例如, 使用 SubmitButtonBackground、SubmitButtonBorder 和 SubmitButtonIcon。

 考虑将“Base”加到超类名称后面

对于使用继承的类关系, 考虑将“Base”加到类名称后面。在 Flex framework 框架中的 ListBase 等类中可以看到这种情况。认为超类抽象时, 可以使用这种做法。

 在方法之间使用空行

类中的所有方法应当以一个空行分隔。它可以提高代码可扫描性以及代码可读性。

 尽可能编写为接口

如果创建的类将属于某个继承关系, 请尽量将类创建为一个接口的具体表示。这里的接口是指 ActionScript 接口, 而不是用户界面。

变量的最佳做法

 使用有意义的变量名称

一般应避免单字符变量名称。还应避免缩写变量名称。

 选择描述性的变量名称

编译器会为您优化它们, 所以长度不会影响文件大小。命名良好的变量和函数可以使代码更容易阅读, 而开发人员也可以减少记录量。

 每行源代码声明一个变量

尽量避免一行代码中出现多个变量声明和分配。如果一行包含多个声明, 开发人员很容易遗漏某个声明。

 以一个空行分隔每个变量声明

为了提高源代码可读性, 每个变量上方应当有一个 ASDoc 注释；变量声明应当在这个注释之后, 而声明之后应当有一个空行。

 使用 ASDoc 样式注释对各个变量做出注释

描述变量推理原因。尽量不要重申变量的用途, 而是描述它的使用方式。请参阅本文“为 ASDoc 注释 ActionScript 源代码”中的示例 ASDoc 注释。

 避免通用名称“object”

避免在变量名称中使用“object”。使用对标识符更有意义的名称。

 始终为变量使用较强的类型

即使类型是 * (无类型), 为变量使用较强的类型有助于表明该变量的目的。类型有助于传达变量的使用和用途。类型较强的变量有一个预设数据类型, 并且只能包含这种类型的数据 (除非更改类型)。

 包含“can”、“is”或“has”的前缀布尔变量名称

这种做法有助于快速找到布尔变量并将它们与其它变量类型区分开；例如: canAnimate、isConnected 或 hasChildren。

 大写常量变量

常量变量应当全部大写并且每个单词以下划线分隔；例如: REMOTE_SERVER_URL、APPLICATION_ID 和 DISCLAIMER_TEXT。

常量变量是应用程序执行过程中不会改变的值。将它们大写后, 您可以将它们与一般 (非常量)变量区分开。

 使常量字符串变量名称与它们的内容匹配

如果常量是字符串, 则使常量变量名称与字符串内容匹配。例如, 字符串“dataEvent”应当在一个名为“DATA_EVENT”的常量变量中。

 为 getter/setters 在变量前加下划线

如果将通过 getter/setter 方法修改变量, 请在它们之前加下划线。

方法的最佳做法

 在方法名称中包含动词

方法通常对某种对象执行某种操作。在方法名中使用操作名；例如: saveUser 或 parseXML。

 将代码限制为每行一个语句

避免在一行中放置多个语句。

 按功能将方法归类

尽可能按职责而不是范围将方法归类。相关方法应放在一起, 以提高代码可理解性和可读性。

 将 getter 方法放在 setter 方法上面

创建 getter/setter 方法时, 首先放置 getter 方法。

 使用 ASDoc 样式注释对各个方法做出注释

在注释中, 说明方法需求的原因并描述可能调用该方法的类的详细使用方法。说明“原因”而不是重申方法所做的操作。请参阅本文“为 ASDoc 注释 ActionScript 源代码”中的示例 ASDoc 注释。

 始终提供一个返回类型, 即使它是空的 (不返回任何内容) 或 * (任何类型)

为所有方法提供一个返回类型。通过查看返回类型, 可以进一步理解方法的用途。

 始终对方法签名使用访问修改符

始终对方法签名使用访问修改符: public、private、protected、internal。

 指定方法自变量的类型

为所有自变量提供一个类型。开发人员编写调用该方法的代码时, 这可能有所帮助。

 将事件处理函数的自变量命名为“event”

这有助于将事件处理函数与应用程序中的其它代码区分开来。其它标准自变量名称为 e 和 evt。与大多数标准一样, 就一种处理方式达成一致并坚持这种方式。

 不要使用空格将方法名称和括号分隔开

尽量编写出简洁、统一、标准化的源代码。

 使用空格将关键字与括号分隔开

设置 if、 for、case 和 while 语句时, 在关键字和括号之间放入一个空格；例如: while ()。

格式的最佳做法

 组织 ActionScript 类

在整个应用程序中, 保持 ActionScript 类的条理性并使它与其余源代码保持一致。当您或其他开发人员稍后需要找到特定代码区域进行快速更改时, 这将有所帮助。

可以将以下结构作为示例:

1. 最初注释。(作者、版本、版权、代码许可证等)。
2. 软件包声明
3. 导入语句
4. 类级元数据标记: Event、Style、Effect (带注释!)
5. 类或接口实施 ASDoc 注释
6. 类或接口语句

7. 静态变量

   1. 公共
   2. 受保护
   3. 私有

8. 实例变量

      
   1. 公共
   2. 受保护
   3. 私有
9. 构造函数
10. Getter/setter 方法 (带支持变量)
11. 方法, 按功能分组

 用四个空格将每个新的代码块缩进

将编辑器设置为按 Tab 键时插入空格而不是制表符。这有助于避免跨平台源代码显示和可读性问题。不同操作系统显示制表符的方式不同。

 用一个空行分隔每个类中的各个方法

创建各个方法, 使 ASDoc 文档注释直接在方法上面。然后是方法签名以及带类型的自变量 (如果自变量存在), 接着是方法主体, 最后是一个空行。

使用空格提高代码可读性

逗号后一般使用一个空格。在 + 和 - 等运算符前后使用空格。

 

MXML 编码标准

为了有助于保持一致性和条理性, 请在 Flex 应用程序中创作或编辑 MXML 源代码时使用以下做法。

元素的最佳做法

 组织元素属性

对元素属性排序: property、events、effects 和 styles。

 将 ID 属性放在第一个属性位置

例如:

 将相关属性归入同一行

例如: paddingLeft、paddingRight、x 和 y 等。

将相关属性分组

如果关联属性太多而无法放入同一行, 请另起一行, 但尽可能将相关属性放在一起。

格式的最佳做法

 使用空行组织 MXML

在无关的 MXML 元素组之间放置一个空行, 如定义过渡的元素以及控制应用程序版面的 HBox 之间。

组织 MXML 文档

使用一致的结构来组织 MXML; 例如:

1. XML 声明
2. 带有 XML 文档中使用的名称空间的根 XML 元素
3. 元数据标记: Event、Style、Effect
4. 样式元素应链接到外部 CSS 文件
5. 脚本标记; 遵循本文“ActionScript 类文件组织最佳做法”部分中列出的标准。
6. 数据相关 MXML 元素、XML、模型等。
7. 过渡元素
8. MXML UI 控制和容器

Flex 的 CSS 编码标准

如果编写样式和外观信息时未遵循编码标准, 它们可能变得很难导航和理解。以下是一些 Flex 开发过程中可使用的 CSS 最佳做法。

 避免内联 CSS

使用 styleName 和自定类定义, 而不是定义 MXML 元素的样式。

 最小化和清理 CSS

将 CSS 保存在一个外部文件中, 并将它引入主应用程序 MXML 文件。尽可能避免将样式嵌入 MXML 代码中。

 将类似的样式定义分组

通过将应用程序的 CSS 文件中类似的样式归入同组, 对它们进行组织。例如, 将所有与文本相关的样式或用于视图的样式归入同组。

 注释样式

注释样式对于稍后需要进行设计更改的人员会有所帮助。

 将 CSS 声明限制为每行一个

将 CSS 限制为每行一个样式定义。这可以提高 CSS 的可读性。

类型选择器的最佳做法

尽可能使用类选择器而不是类型选择器

尽量定义自定类而不是覆盖 Flex 控制的默认样式。这需要设置控制的 styleName 属性, 但可以提高之后的灵活性。

类选择器的最佳做法

 为类选择器名称使用 lowerCamelCase (第一个词的首字母小写, 后面每个词的首字母大写)

这是整个社区的最佳做法, 应当遵循它。

 避免在类选择器名称中使用下划线

这也是整个社区的最佳做法, 应当遵循它。

避免根据外观命名类选择器

尽量根据类选择器的功能而不是视觉外观命名它们。
例如, 使用 warningText 而不是 yellowText, 使用 errorText 而不是 redText
如果使用 yellowText, 当警告文本颜色改变时, 这个名称无法再描述结果。不应根据外观编写固定名称。

使用一致的命名系统
为样式使用一致的命名惯例。

 

为 ASDoc 注释 ActionScript 源代码

在源代码中加入注释有助于说明代码所做操作及其存在原因。使用 ASDoc 是为代码库创建和维护现有文档的绝佳方式。您可以使用代码中的注释简化代码更新, 还可以使用 ASDoc 工具制作文档。

注意: 某些情况下, 紧迫的截止日期使得很难在软件开发过程中全面注释代码。决定是否应跳过注释操作时, 请权衡项目及目前情况的利弊。

注释格式的最佳做法

遵循以下使用的标准 ASDoc 注释格式:

/**

 *

 * ASDoc documentation comment.

 *

 * 
Another chunk of information related to this code block.

 *

 */

 使用空格和前导星号提高注释的可读性

保持注释的简洁性, 以免与源代码混淆在一起。这可以为使用该源代码的其他开发人员改善可读性。

 使用受支持的 HTML 对 ASDoc 输出进行格式化

使用 ASDoc 支持的任何 HTML 标记改善通过 ASDoc 创建的 HTML 文件呈现的文档注释的可读性。

 为主要描述编写完整而简洁的第一句

ASDoc 注释的主要描述的第一句应当包含所声明项目完整而简洁的描述。这一句将用于填充该项目的类的 ASDoc HTML 页面顶部的摘要表。

使用 ASDoc 注释类的最佳做法

 为每个类创建实用的注释

将注释直接放在类声明上面。列出代码功能并说明与其它类的关系。描述为何存在继承关系。

 使用 @private 对 ASDoc 隐藏类

如果不应记录类, 可在注释的任何位置使用 @private 标记。

 如果方法包含返回类型, 则使用 @return

如果方法包含返回值, 使用 @return 说明所返回的值。

 将 @see 用于存在关系的项目

如果注释的项目与其它类或软件包存在关系, 使用 @see 标记说明这些关系。

 不要在 ASDoc 注释中使用特殊字符

如果代码包含非 UTF-8 字符, ASDoc 将失败。

 注释文本应当始终在任何 @ 标记之前

如果未将注释文本放在 @ 标记上面, 它将作为 @ 标记的自变量进行解释。但是, @private 标记可以放在 ASDoc 注释的任何位置。

使用 ASDoc 注释变量的最佳做法

 描述变量的使用方式

创建注释, 它们包含如何使用变量的实用信息。描述“为何”而不是“什么”。

使用 ASDoc 注释方法和接口的最佳做法

 为所有方法和接口创建实用注释

将注释直接放在方法声明上面。列出方法的用途和任何实施详细信息。尽量避免简单说明方法所做的操作。也可以说明方法返回值的原因

使用 ASDoc 注释事件的最佳做法

 为事件类型使用标准类路径

这可以确保事件的唯一性并且它不会与系统中其它位置的事件发生冲突。例如, 考虑将您添加第三方代码的项目加入一个应用程序, 使用标准类路径可以确保应用程序的活动是唯一的。

例如: com.seantheflexguy.burrow.events.RSSDataEvent

 

应用程序架构

Flex 应用程序是一些复杂系统, 它们从构思缜密的规划中大大受益。使用可靠的方法确保构建的应用程序结构完善。

 创建用例

为应用程序中的各个目标或任务生成用例。从操作者的角度定义用例。操作者通常就是您构建的应用程序的用户。可以围绕用户执行的任何交互创建用例。操作者也可以是应用程序本身、另一个应用程序或 Web 服务器等外部系统。

 考虑使用 UML

使用统一建模语言 (UML) 描述应用程序的主类和数据模型有助于细化应用程序中的对象并避免今后可能的代码返工。

 考虑使用代码生成

有许多工具可以从 UML 图表生成 ActionScript 3.0 源代码。有时这可以节省时间。值得一试的两个工具是 Sparx Systems 提供的 Enterprise Architectand 和免费的 Violet ActionScript 3 Generator (VASGen)。

 考虑使用设计模式

有两本好书: “设计模式: 可重用、面向对象的软件元素”和“从设计模式入手”。

应用程序开发框架

使用框架可以大幅提高成功几率, 应用程序包含大量源代码时尤为如此。

 考虑使用应用程序开发框架

对于开发 Flex 应用程序时是否应使用框架存在一些争议。对于企业级应用程序以及开发人员小组, 一般倾向于推荐框架。我的个人偏好和建议是使用应用程序开发框架。这可以为代码库架构实现一种公共语言, 并为应用程序开发和可伸缩性指明方向。

 将框架用于基于小组的开发工作

框架可以帮助不同小组一致合作, 并降低开发工作重复的几率。 

 Mate

Mate (发音为“mah-tay”) 是一个基于标记的应用程序开发框架, 可与 Flex 一起使用。Mate 是一种非侵入式框架, 它允许松耦合型代码库。

 Cairngorm

Cairngorm 是 Flex 应用程序开发的实际标准。如果不了解 Cairngorm, 您绝对应当考虑学习一下。有关 Cairngorm 的更多信息, 请参阅这篇好文章“介绍 Cairngorm”*。Adobe Consulting 使用 Cairngorm 并将它用于开发工作。

 PureMVC

这是一个纯 ActionScript 3.0 模型-视图-控制器应用程序开发框架。 PureMVC 的制造商 Futurescale 将它描述为：“PureMVC 是一款根据经典的模型-视图-控制器设计元模式创建应用程序的轻量级框架...PureMVC 框架的主要目的很直接：帮助您将应用程序的编码问题分为三个离散层；模型、视图和控制器。”

 其它框架

还有许多其它应用程序框架可以与 Flex 一起使用, 它们甚至可以直接用于 AS3 项目。

 知道何时不用框架

有时框架对于某个应用程序而言过于强大。如果您是这个应用程序的唯一开发人员并且在它的整个生命周期中始终如此, 那么您可能无法从框架中受益。如果您开发的内容十分简单, 如条幅广告, 那么也可以跳过框架。应用程序开发框架提供的强大的功能集一般不适合十分简单的应用程序, 这类应用程序的数据操作有限并且事件很少。要了解其它视角, 请参阅 Steven Webster* 的这篇经典博客文章, 它讨论何时应该以及何时不应该使用应用程序开发框架。

集成单元测试

单元测试可以确保代码库的质量。编写测试用例可以实现更可靠、更出色的代码。测试代码有助于找出错误并节省调试时间。以下是实施单元测试时可使用的几个最佳做法。

 测试行为而不是测试方法

并非始终需要编写代码来测试私有方法。应当根据具体情况对此作出评估。编写代码测试对象的公共 API。私有方法通常由类内部用于支持其公共 API。

 使用“太简单, 所以不会出错”规则

代码库测试切勿过度。如果方法是十分简单的单行方法, 如 getter 方法, 则无需为它编写测试用例。

 在测试用例中使用标准 OOP 最佳做法

使用编写其余应用程序所使用的相同 OO 方法。重构测试用例, 将常用功能适当移入基本类中。

 使用简洁、明确的测试方法名称

使用应用程序代码库的其它地方使用的同一方法命名惯例。避免为测试用例方法使用通用名称。这可以帮助其他开发人员轻松理解方法的关系、职责和用途。

 编写简单的测试用例方法

保持测试用例的简洁性, 并限制在它们中所作的决策。

 尽可能在声明方法中使用静态值

这可以降低测试用例出错的几率, 并且可以提高测试代码的可维护性和可理解性。

 记录测试代码

添加注释, 它们说明测试内容和原因。并列出有关测试的任何特殊环境。

 创建独立单元测试

每个单元测试应当为各个方法执行单一行为。

 将声明限制为每个测试用例一个

一个测试用例中包含多个声明可能导致性能问题。并且, 如果某个声明失败, 不会执行其它声明, 直至第一个声明成功通过。

 

Flex 开发最佳做法回顾

这些做法可以应用到所有 Flex 应用程序。请查看这些做法:

 创建和使用 assets 目录

 使用 assets 目录中的子目录

 使用 SWF 目录

 使用 images 目录

 使用 fonts 目录

 使用 audio 目录

 使用 video 目录

 使用 XML 目录

 不要将动词、形容词或副词用于软件包名称

 将复数名词用于软件包

 根据软件包中的类命名软件包

 使用类推动 OOP

 将名词用于类名称

 将类主体中定义的可执行代码量降最低

 使实例变量与自变量匹配

 创建类时使用经典的一般惯例

 将类类型 (formatter、validator、event 和 error) 加在类名称后面

 将外观类型加到类名称后面

 考虑将“Base”加到超类名称后面

 不要在类名称中使用空格

 在方法之间使用空行

 尽可能编写为接口

 接口名称应当为形容词

 使用有意义、描述性的变量名称

 每行源代码声明一个变量

 以一个空行分隔每个变量声明

 使用 ASDoc 样式注释对各个变量做出注释

 避免将通用名称“object”用于变量

 始终为变量使用较强的类型

 包含“can”、“is”或“has”的前缀布尔变量名称

 大写常量变量

 使常量字符串变量名称与它们的内容匹配

 在方法名称中包含动词

 将代码限制为每行一个语句

 按功能将方法归类

 将 getter 方法放在 setter 方法上面

 使用 ASDoc 样式注释对各个方法做出注释

 始终提供一个返回类型, 即使它是空的 (不返回任何内容) 或 * (任何类型)

 始终对方法签名使用访问修改符

 指定方法自变量的类型

 将 setter 方法的自变量命名为“value”

 将事件处理函数的自变量命名为“event”

 不要使用空格将方法名称和括号分隔开

 使用空格将关键字与括号分隔开

 组织 ActionScript 类

 用四个空格将每个新的代码块缩进

 用一个空行分隔每个类中的各个方法

 使用空格提高代码可读性

 组织 MXML 元素属性

 将 ID 属性放在 MXML 元素的第一个属性位置

 将相关属性归入同一行

 将 MXML 元素的相关属性分组

 将元标记放在它们标记的属性或方法上面

 使用空行组织 MXML

 组织 MXML 文档

 避免内联 CSS

 最小化和清理 CSS

 将类似的样式定义分组

 注释样式

 将 CSS 声明限制为每行一个

 将 UpperCamelCase ( 第一个词的首字母, 以及后面每个词的首字母都大写) 用于类型选择器名称

 尽可能使用类选择器而不是类型选择器

 为类选择器名称使用 lowerCamelCase (第一个词的首字母小写, 后面每个词的首字母大写)

 避免在类选择器名称中使用下划线

 避免根据外观命名类选择器

 使用一致的命名系统

 遵循标准 ASDoc 注释格式

 使用空格和前导星号提高注释的可读性

 使用受支持的 HTML 对 ASDoc 输出进行格式化

 为主要描述编写完整而简洁的第一句

 为每个类创建实用的注释

 使用 @private 对 ASDoc 隐藏类

 如果方法包含返回类型, 则使用 @return

 将 @see 用于存在关系的项目

 不要在 ASDoc 注释中使用特殊字符

 注释文本应当始终在任何 @ 标记之前

 描述变量的使用方式

 为所有方法和接口创建实用注释

 为事件类型使用标准类路径

 创建用例

 考虑使用 UML

 考虑使用代码生成

 考虑使用设计模式

 考虑使用应用程序开发框架

 将框架用于基于小组的开发工作

 知道何时不用框架

 测试行为而不是测试方法

 使用“太简单, 所以不会出错”规则

 在测试用例中使用标准 OOP 最佳做法

 使用简洁、明确的测试方法名称

 编写简单的测试用例方法

 尽可能在声明方法中使用静态值

 记录测试代码

 创建独立单元测试

 将声明限制为每个测试用例一个

后续工作

Ted Patrick 曾针对 Flex 最佳做法进行过多次演讲, 他提出以下观点, 我认为它也适用于本文:

“针对 Flex 的每个项目都有所不同, 因此最佳做法因涉及的小组和项目不同而异。我看到有些适合较小小组的项目做法不适用于较大的小组, 反之亦然。这是我在过去三年中观察许多项目后得出的 Flex 最佳做法心得。我的建议在许多情况下并不会令人吃惊, 因为它们是经典的软件开发原则。”

有关 Flex 最佳做法的更多信息, 请参阅:

• Flex SDK 编码惯例和最佳做法* - Adobe
• 视频: Flex 最佳做法* - James Ward
• Adobe Flex 编码指导方针* - DClick