amazeui学习笔记二（进阶开发4）-凯发真人娱乐

一、总结

1、注释规范总原则：

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

2、变量命名规则（和之前的c 和java一样）：

常量全大写 uppercase_word
变量驼峰 camelname
类名驼峰，并且首字母要大写 camelname

3、注释书写习惯：

推荐用英文

标点符号用中文全角

英文与中文之间要用一个空格分开

// 注释 与 /* 注释 */

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

基本编码规范

allmobilize javascript style guide
cmd 模块定义规范

代码质量控制工具

amaze ui 使用 ~~jshint 和 jscs~~eslint控制代码质量。

详细设置参见 ~~.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;

命名规范

基本原则

[a-z\d\-]

用连字符连接、添加 am 命名空间

data-am-trigger

amui

:

.

.trigger('open:modal:amui')

常量全大写 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 命名空间

注释规范

总原则

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

什么时候需要添加注释

某段代码的写法，需要注释说明 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 合并后，源码的层次清晰。

注释书写规范

推荐用英文

标点符号用中文全角

英文与中文之间要用一个空格分开

// 注释 与 /* 注释 */

文档规范

readme.md

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

# 模块名称
-----
该模块的概要介绍。
------
## 使用说明
如何使用该模块，可以根据组件的具体特征，合理组织。
## api
需要提供 api 说明，属性、方法、事件等。
## 使用示例

history.md

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

参考链接

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

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

amazeui学习笔记二（进阶开发4）-凯发真人娱乐

一、总结

二、javascript规范rules

目录

基本编码规范

代码质量控制工具

jquery / zepto.js 使用规范

代码格式

命名规范

基本原则

html data api

javascript

接口命名规范

注释规范

总原则

什么时候需要添加注释

注释书写规范

文档规范

readme.md

history.md

参考链接

amazeui学习笔记二（进阶开发4）--javascript规范rules的相关教程结束。

相关推荐

amazeui学习笔记二（进阶开发5）--web 组件开发规范rules