JavaScript库 开发流程

以下是taobao开发KISSY库德开发流程。感觉不错，学习了，有不少地方值得借鉴。

原文地址是：http://kissyteam.github.com/docs/kissy/quickstart/yourwidgets.html

将 JS 代码组件化的好处:

1. 提高代码复用
2. 模块间保持独立, 不会导致多个开发人员合作时产生的冲突
3. 封装性好, 只提供 API 接口给外部调用

KISSY 中, 通过 add( name, fn ) 方法来添加新的模块. 在 KISSY 内部, 代码也是这么组织的.

下面通过个小例子来说明如何开发自定义组件.

一些说明:

1. 首先, 想好组件的名字, 见名知意, 模块名字统一小写, 而暴露给外部的组件名称使用单词首字母大写, 如 StarRating ;
2. 通过 KISSY.add('starrating', function(S){ }); 加入新模块到 KISSY 中, 这里也可以使用 KISSY.app('XXX'); 创建特定的应用, 然后用 XXX.add('starrating', function(S){}); 给特定应用 XXX 添加一个模块;
3. 接下来是声明一些模块内的公共变量, 像 S.DOM, S.Event 都会用到, 另外一些如组件自己的 class 钩子;
4. 默认的配置信息, defaultConfig , 提供了使用者如果没有设置时的默认值;
5. 通过 S.augment(StarRating, { }); 添加属性及方法, 每个方法在注释中写明含义, 入口参数及其类型. 另外, 开发者需要想好哪些属性/方法需要对外提供及命名方式如何等. 在这个例子中, 只添加了 _init 私有方法, 用来构建所需 DOM, 绑定事件;
6. 最后, 在使用时只需要创建一个对象即可, 如, new S.StarRating('#J_Rating', config) ;

在动手写 KISSY 组件之前, 还需要了解一下 KISSY 组件的开发流程相信会对你有用的.

KISSY 组件开发流程¶

在开发过程中, 开发者(就拿我来举例吧), 经常会出现:

1. 需求过来: 稍加理清下思路, 急急忙忙就开始写代码了, 然后写到七八分了, 才发现貌似一开始就没完全明白需求是什么...然后只能重构-.-
2. 重构第一次: 现在完全明白需求是什么了, 嗯嗯, 基本上是完全删除原来的代码, 按照新需求写, 其间要考虑 n 多种情况以尽可能满足所有场景下的需求, 导致一个 js 源文件打开后的滚动条缩得很短.
3. 呃. 太长了, 未来及现在的自己都不愿意再去看这段代码, 所以, 即将面临着再一次重构.
4. 重构第二次, 拆分大逻辑, 删减不必要的代码, 保持 JS 文件的精简, 代码组织的也比较好看, 易懂.
5. 问题又来了, 精简之后, 只保留了基本功能, 一些其他的功能被完全删除了, 但这些功能又需要, 为了尽量不增加核心 JS 文件, 所以再次重构.
6. 这次重构是针对扩展来得, 在避免修改核心代码的前提下, 编写适合特定需求的扩展代码.

我们需要避免这些问题(需求不明确, 盲目动手, 代码冗长, 写了后面的忘了前面的逻辑, 导致可扩展性差, 可复用性也差). HOW?

以前听人提过 Literate Programming(文学化编程) [1] 一词, 说的是:

Literate Programming

文学编程自由地表达逻辑, 而且它用人类日常使用的语言写出来, 就好像一篇文章一样, 让开发者用他们自己思维内在的逻辑和流程所要求的顺序开发程序.

现在越来越觉得, 其实, 写代码和写文章一样, 一个代码完成, 给别人阅读, 就得像看书一样, 从头至尾地, 能清晰的让阅读的人知道这代码实现的功能是什么, 适合/不适合哪些情况, 在使用时有哪些需要注意的地方;

在实际开发中, 除了给代码加注释外, 还有很多代码不能做的事情, 需要更多的文档来支持开发, 下面拿 ImageZoom slide [2] 为例说明一下:

总体流程, 如下所示:

应用场景分析¶

一个需求到来, 比如这个图片放大效果, 首先我们需要这个功能能用在哪些地方, 或哪些网站上已经使用了, 如果有的话, 就对比一下不同的情况下不同的要求, 如 #slide4 . 这样以后, 对比自己的需求, 想好要实现什么功能, 哪些功能保留, 哪些功能不需要, —- 明确需求;

同类组件调研¶

需求明确之后, 查找现有的同类组件, 看看他们针对这个问题, 是怎么实现的, 实现哪些功能, 哪些可以借鉴的地方, 哪些不足的地方要避免或者改进, 如 #slide6 , —- 明确要实现的功能有哪些;

功能点分析¶

分离出完成整个功能需要的几个核心功能点, 并针对各个功能点逐个描述, 如 #slide8 , 这也可以帮你理清思路, —- 进一步明确待实现功能;

技术方案¶

针对上述的几个功能点, 分别给出实现方案, 或者其他的技术难点, 又或者是算法上的分析等, 如 #slide9 , — 明确如何实现;

Public API¶

设计好的公共 API , 并在此说明, 也可以根据使用场景, 给出一些范例来说明 API 的使用, 如 #slide14 , 这里可以在开始时设计的尽量精简些, —- 明确 API 接口;

开发计划¶

简略或者详细的制定一个开发计划, 及发布的版本和时间等, —- 明确进度;

其他¶

可选的部分, 用于记录所有开发过程中碰到的杂类问题或者和其他同学的讨论.

我们建议每个 KISSY 组件下, 都存放一个 slide.html, 其内容包含上述几部分内容. 这个 slide 随着你的开发过程的推进, 也会不断添加更新, 最后发布时连同组件源代码一起, 形成非常好的知识体系, 这样, 给别人或是几十年后的自己阅读, 也会像看文章一样的有条理.

KISSY 组件目录及代码组织¶

关于代码组织, [4] 和 KISSY 工程 README 中都有些简单介绍, 下面简单说明下推荐的目录结构:

目录结构¶

• widget-name

  • assets: 存放 css, img 等相关文件

  • build.properties/build.xml: 打包配置文件

  • widget-name.js: 组件核心代码

  • slide.html: 上面所说的调研文档

  • test.html: 测试文件

  • tests: 测试用例目录
    • widget-name-spec.js: 测试用例脚本文件, 可以有多个, 但务必以-spec为后缀

代码组织¶

• 内部代码组织：采用 module, sub module 来分拆和组织代码
• 外部调用接口：component 形式，包括工具型组件 utils 和 UI 型组件 widgets

命名约定¶

原则：尽量避免潜在冲突，同时力求精简短小和见名知意。

• 全局变量: g_ks_comp_xxx 比如: g_ks_suggest_callback

• class/id 命名: ks-comp[-xxx] 比如: ks-editor-toolbar-item

• data 属性命名: data-ks-comp[-xxx] 比如: data-ks-suggest

• hook 规范: KS_Comp 比如: KS_Switchable

• config 属性:
  • 以小驼峰形式, 比如 minDate;
  • 常用 config 属性, 如trigger, container, containerCls, triggerType, type, 固定名字, 所有组件保持一致;
  • config 的属性值, 对于位置, 用数组形式, 比如 offset: [10, 20];

注意: 为了避免太冗长, 在保持清晰和无潜在冲突的情况下, 可以打破原则, 比如：

<div class="KS_Widget" data-widget-type="Tabs" data-widget-config="{...}">

罗罗嗦嗦这么一大堆后, 不知道你是否觉得简单? 非常推荐基于 KISSY 尝试去实现一个组件, 一切都很简单的^o^

注意: 上面的 StarScore 组件仅是示范，实际应用中，还更复杂些，这个组件将会在 KISSY 1.2 时正式发布.