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、注释书写习惯:
- 源码中的注释,推荐用英文。
- 含有中文时,标点符号用中文全角。
- 中英文夹杂时, 英文与中文之间要用一个空格分开。
- 注释标识符与注释内容要用一个空格分开:
// 注释
与/* 注释 */
。
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
var x = 1;
var y = 2;for (var i = 0, j = arr.length; i < j; i++) { }
Invalid
var x = 1,y = 2;
命名规范
基本原则
- 文件和目录名只能包含
[a-z\d\-]
,并以英文字母开头 - 首选合适的英文单词
- Data API 命名使用小写、用连字符连接、添加
am
命名空间,如data-am-trigger
- 事件名使用小写字母,包含模块名及
amui
命名空间名,使用:
连接(Zepto 不支持使用.
链接的自定义事件),如.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 命名空间 |
注释规范
总原则
- 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 合并后,源码的层次清晰。
注释书写规范
- 源码中的注释,推荐用英文。
- 含有中文时,标点符号用中文全角。
- 中英文夹杂时, 英文与中文之间要用一个空格分开。
- 注释标识符与注释内容要用一个空格分开:
// 注释
与/* 注释 */
。
文档规范
README.md
每个组件必须有 README.md 文件,用来描述组件的基本情况。
# 模块名称-----该模块的概要介绍。------## 使用说明如何使用该模块,可以根据组件的具体特征,合理组织。## API需要提供 API 说明,属性、方法、事件等。## 使用示例
HISTORY.md
记录组件的变更,最好和 issues
进行关联。请阅读历史记录书写规范。
参考链接
Amaze UI 的编码规范参考了社区里一些先行者的做法,在此致谢!
- 注释规范
- 编码风格
- 编码与文档的讨论
- 常用词命名统一表
转载于:https://www.cnblogs.com/Renyi-Fan/p/9005679.html
amazeui学习笔记二(进阶开发4)--JavaScript规范Rules相关推荐
- amazeui学习笔记二(进阶开发2)--Web组件简介Web Component
amazeui学习笔记二(进阶开发2)--Web组件简介Web Component 一.总结 1.amaze ui:amaze ui是一个web 组件, 由模板(hbs).样式(LESS).交互(JS ...
- Springboot学习笔记(二)Web开发
前言: 学习B站UP主狂神说视频笔记整理视频链接 狂神笔记链接 上篇笔记链接-Springboot学习笔记(一)快速上手 Web开发 静态资源 在以往的SpringMVC中所有静态资源或者页面应该放在 ...
- Docker学习笔记(二)--进阶篇
文章目录 1. Docker复杂安装 1.1 安装Mysql的主从复制 主从搭建步骤 1.2 安装Redis集群 1.2.1 面试题:1~2亿条数据需要缓存,请问应该怎样设计 1.2.2 三主三从集群 ...
- Polyworks脚本开发学习笔记(二十)-补充几个常见操作指令的使用
Polyworks脚本开发学习笔记(二十)-补充几个常见操作指令的使用 大概要写到结尾了,最后几篇就将手册的各常用命令再看一遍,组合一下,并列举出常见的一些有用的操作. DATA_COLOR_MAP数 ...
- Polyworks脚本开发学习笔记(二)-TREEVIEW基本操作
Polyworks脚本开发学习笔记(二)-TREEVIEW对象基本操作 TREEVIEW对象选择 选择/不选对象 TREEVIEW OBJECT SELECT ALL 全部对象选择,包括参考/数据/对 ...
- Polyworks脚本开发学习笔记(二二)-调取视角用脚本自动生成报告
Polyworks脚本开发学习笔记(二二)-调取视角用脚本自动生成报告 Polyworks中,3D场景的视图可用标准视角及等轴侧视角.项目视角等方式调用,也可以用txt格式保存下来调用,如果以脚本的形 ...
- 华清远见fs4412开发板学习笔记(二)
fs4412开发板学习笔记(二) Linux 1.终端操作 1)打开终端 ctrl + alt + t 2)放大 ctrl + shift + "+" 3)缩小 ctrl + &q ...
- GEE(Google Earth Engine) 最基础代码学习笔记二 —— JavaScript 语言
GEE(Google Earth Engine) 学习笔记二 Javascript 语言 1. 注释 print('Hello World!'); 如果要注释,则在代码前面加//,比如: // pri ...
- amazeui学习笔记--css(布局相关3)--辅助类Utility
amazeui学习笔记--css(布局相关3)--辅助类Utility 一.总结 1.元素清除浮动: 添加 am-cf 这个 class 即可 2.水平滚动: .am-scrollable-horiz ...
最新文章
- 深入浅出统计学(十二)置信区间
- 固件模块之间的关系 C语言里面的模块
- 找到一本适合自己的SQL Server 2008入门书
- getAttribute() 与 attr() 的区别
- CTF web题总结--任意文件下载
- linux可以ping通,Linux可以Ping通但不能traceroute
- 截屏录屏软件分享 FSCapture、Snipaste【目前见过的最好用的录屏软件】
- java redis 存session_JavaWeb: Redis存储Session方案
- MySQL监控系统Lepus的搭建
- C/C++:Winsock网络编程—ping命令的简单实现
- 俺也试着搞了一个vue组件库
- Java高并发BlockingQueue重要的实现类二
- Prescan(七):prescan中air传感器的配置
- qt+opencv实现敏感区域移动侦测
- Kobe -接小球游戏
- pt-table-checksum 使用实践
- 学 计算机 知识视频,教你学电脑——计算机基础知识【视频】*
- 385高校毕业设计选题
- 关于innerHTML的用法,以及数据覆盖问题
- python爬虫解析数据包_Python网络爬虫之三种数据解析方式