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

时间：2023-02-08 23:34:20

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

基本编码规范

代码质量控制工具

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 不兼容的选择符。

问题：

代码格式

  • 缩进 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-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 会完成压缩体积工作）
常用词 说明
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 的编码规范参考了社区里一些先行者的做法，在此致谢！

相关文章