Amaze UI JavaScript 规范

基本编码规范

• AllMobilize JavaScript Style Guide
• CMD 模块定义规范

代码质量控制工具

Amaze UI 使用 JSHint 和 JSCS 控制代码质量。

详细设置参见 .jshintrc、.jscsrc。

（部分直接使用第三方库的代码未通过质量控制工具检测。）

jQuery / Zepto.js 使用规范

为提高代码执行效率，为二者兼容提供可能，在使用 jQuery / Zepto.js 时做以下约定：

• 存放 jQuery / Zepto 对象的变量以 $ 开头；
• 禁止使用 slideUp/Down() fadeIn/fadeOut() 等方法；
• 尽量不使用 animate() 方法；
• 使用和 Zepto.js 兼容的基本选择符，不使用效率较低且与 Zepto.js 不兼容的选择符。

问题：

• 自定义事件命名空间： Zepto.js 不支持 . 语法，只能使用 : 语法。
• http://zeptojs.com/#event
• http://api.jquery.com/event.namespace/

代码格式

• 缩进 2 个空格；
• 使用多 var 模式声明变量：更容易维护，比如要删除第一个变量或者最后一个变量时，多 var 模式直接删除即可，单 var 还要去修改别的行（for 循环例外）；

Valid

var x = 1;
var y = 2;

for (var i = 0, j = arr.length; i < j; i++) {
}

Invalid

var x = 1,
    y = 2;

命名规范

基本原则

1. 文件和目录名只能包含 [a-z\d\-]，并以英文字母开头
2. 首选合适的英文单词
3. Data API 命名使用小写、用连字符连接、添加 am 命名空间，如 data-am-trigger
4. 事件名使用小写字母，包含模块名及 amui 命名空间名，使用 : 连接（Zepto 不支持使用 . 链接的自定义事件），如 .trigger('open:modal:amui')
5. 符合规范
   • 常量全大写 UPPERCASE_WORD
   • 变量驼峰 camelName
   • 类名驼峰，并且首字母要大写 CamelName

HTML Data API

• 基本: data-am-{组件名}，如 data-am-modal、data-am-navbar-qrcode
• 传参: data-am-modal="{key1: 'val1', key2: false}"，core.js 中增加一个专门解析参数的函数

JavaScript

• 自定义事件命名：{自定义事件名}:{组件名}:{后缀}，Zepto 不支持 . 分隔的自定义事件语法，官方示例中使用 : 分隔，如 closed:modal:amui。Zepto 中没有 event.namespace，这样的命名方式只用于清晰区分不同模块的自定义事件。另外，按照 Zepto 官方示例，应该写成 amui:modal:closed，为跟 jQuery 的写法统一，颠倒顺序书写。
• 默认绑定事件：事件名（内置事件，非自定义事件）采用 {事件名}.{组件名}.{命名空间}，如 $(document).on('click.modal.amui',...。
  • 取消所有默认绑定事件： $(document).off('.amui',...
  • 取消特定组件的默认绑定事件： $(document).off('.modal.amui',...

接口命名规范

通过接口规范，统一模块对外接口的命名，形成一致的编写习惯。

规则：

• 可读性强，见名晓义。
• 尽量不与 jQuery 社区已有的习惯冲突。
• 尽量写全。不用缩写，除非是下面列表中约定的。（变量以表达清楚为目标，uglify 会完成压缩体积工作）

注释规范

总原则

• As short as possible（如无必要，勿增注释）：尽量提高代码本身的清晰性、可读性。
• As long as necessary（如有必要，尽量详尽）：合理的注释、空行排版等，可以让代码更易阅读、更具美感。

总之，注释的目的是： 提高代码的可读性，从而提高代码的可维护性。

什么时候需要添加注释

• 某段代码的写法，需要注释说明 why 时：

// Using loop is more efficient than `rest = slice.call(arguments, 1)`.
for (i = 1, len = arguments.length; i < len; i++) {
    rest[i - 1] = arguments[i];
}

• 添加上注释，能让代码结构更清晰时：

init: function(selector, context, rootjQuery) {
    var match, elem, ret, doc;

    // Handle $(""), $(null), or $(undefined)
    if ( !selector ) {
        ...
    }

    // Handle $(DOMElement)
    if ( selector.nodeType ) {
        ...
    }

    // The body element only exists once, optimize finding it
    if ( typeof selector === "string" ) {
        ...
     }
}

• 有借鉴、使用第三方代码，需要说明时：

// Inspired by https://github.com/jquery/jquery/blob/master/src/core.js
function ready() {
    ...
}

• 文件最后空一行，可以保证在 combo 合并后，源码的层次清晰。

注释书写规范

1. 源码中的注释，推荐用英文。
2. 含有中文时，标点符号用中文全角。
3. 中英文夹杂时， 英文与中文之间要用一个空格分开。
4. 注释标识符与注释内容要用一个空格分开：// 注释 与 /* 注释 */。

文档规范

README.md

每个组件必须有 README.md 文件，用来描述组件的基本情况。

# 模块名称

-----

该模块的概要介绍。

------

## 使用说明

如何使用该模块，可以根据组件的具体特征，合理组织。

## API

需要提供 API 说明，属性、方法、事件等。

## 使用示例

HISTORY.md

记录组件的变更，最好和 issues 进行关联。请阅读历史记录书写规范。

参考链接

Amaze UI 的编码规范参考了社区里一些先行者的做法，在此致谢！

• 注释规范
• 编码风格
• 编码与文档的讨论
• 常用词命名统一表