Amaze UI JavaScript 规范


基本编码规范

代码质量控制工具

Amaze UI 使用 JSHintJSCS 控制代码质量。

详细设置参见 .jshintrc.jscsrc

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

jQuery / Zepto.js 使用规范

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

问题:

代码格式

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

JavaScript

接口命名规范

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

规则:

常用词 说明
options 表示选项,与 jQuery 社区保持一致,不要用 config, opts 等
active 表示当前,不要用 current 等
index 表示索引,不要用 idx 等
trigger 触点元素
triggerType 触发类型、方式
context 表示传入的 this 对象
object 推荐写全,不推荐简写为 o, obj 等
element 推荐写全,不推荐简写为 el, elem 等
length 不要写成 len, l
prev previous 的缩写
next next 下一个
constructor 不能写成 ctor
easing 示动画平滑函数
min minimize 的缩写
max maximize 的缩写
DOM 不要写成 dom, Dom
.hbs 使用 hbs 后缀表示模版
btn button 的缩写
link 超链接
title 主要文本
img 图片路径(img标签src属性)
dataset html5 data-xxx 数据接口
theme 主题
className 类名
classNameSpace class 命名空间

注释规范

总原则

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

什么时候需要添加注释

// 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() {
    ...
}

注释书写规范

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

文档规范

README.md

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

# 模块名称

-----

该模块的概要介绍。

------

## 使用说明

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

## API

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

## 使用示例

HISTORY.md

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

参考链接

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