amazeui学习笔记二（进阶开发4）--JavaScript规范Rules

amazeui学习笔记二（进阶开发4）--JavaScript规范Rules

一、总结

1、注释规范总原则： 

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

2、变量命名规则（和之前的C++和Java一样）：

• 常量全大写 UPPERCASE_WORD
• 变量驼峰 camelName
• 类名驼峰，并且首字母要大写 CamelName

3、注释书写习惯：

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

4、接口命名规范：（那些名词有特定的缩写，比如button缩写成btn）

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

常用词	说明
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 命名空间

二、JavaScript规范Rules

目录

• 基本编码规范
• 代码质量控制工具
• jQuery / Zepto.js 使用规范
• 代码格式
• 命名规范
  • 基本原则
  • HTML Data API
  • JavaScript
• 接口命名规范
• 注释规范
  • 总原则
  • 什么时候需要添加注释
  • 注释书写规范
• 文档规范
  • README.md
  • HISTORY.md
• 参考链接

基本编码规范

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

代码质量控制工具

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

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

2016.04.20 替换为 ESLint，参见 Welcoming JSCS to ESLint

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

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

 Copy

var x = 1;
var y = 2;

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

Invalid

 Copy

var x = 1,
    y = 2;

命名规范

基本原则

1. 文件和目录名只能包含 [a-zd-]，并以英文字母开头
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 会完成压缩体积工作）

常用词	说明
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 命名空间

注释规范

总原则

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

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

什么时候需要添加注释

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

 Copy

// 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];
}

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

 Copy

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

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

 Copy

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

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