Amaze UI

Amaze UI JavaScript 规范


基本编码规范

代码质量控制工具

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

详细设置参见 .eslintrc

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

代码格式

  • 缩进 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 命名空间名,使用 . 连接,如 .trigger('open.modal.amui')
  5. 符合规范
    • 常量全大写 UPPERCASE_WORD
    • 变量驼峰 camelName
    • 类名驼峰,并且首字母要大写 CamelName

HTML Data API

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

JavaScript

  • 自定义事件命名:{自定义事件名}.{组件名}.{后缀},如 closed.modal.amui
  • 默认绑定事件:事件名(内置事件,非自定义事件)采用 {事件名}.{组件名}.{命名空间},如 $(document).on('click.modal.amui',...
    • 取消所有默认绑定事件: $(document).off('.amui',...
    • 取消特定组件的默认绑定事件: $(document).off('.modal.amui',...

接口命名规范

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

规则:

  • 可读性强,见名晓义。
  • 尽量不与 jQuery 社区已有的习惯冲突。
  • 尽量写全。不用缩写,除非是下面列表中约定的。(变量以表达清楚为目标,uglify 会完成压缩体积工作)
常用词说明
options表示选项,与 jQuery 社区保持一致,不要用 config, opts 等
active表示当前,不要用 current 等
index表示索引,不要用 idx 等
trigger触点元素
triggerType触发类型、方式
context表示传入的 this 对象
object推荐写全,不推荐简写为 o, obj 等
element推荐写全,不推荐简写为 el, elem 等
length不要写成 len, l
prevprevious 的缩写
nextnext 下一个
constructor不能写成 ctor
easing示动画平滑函数
minminimize 的缩写
maxmaximize 的缩写
DOM不要写成 dom, Dom
.hbs使用 hbs 后缀表示模版
btnbutton 的缩写
link超链接
title主要文本
img图片路径(img标签src属性)
datasethtml5 data-xxx 数据接口
theme主题
className类名
classNameSpaceclass 命名空间

注释规范

总原则

  • 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 的编码规范参考了社区里一些先行者的做法,在此致谢!