命名规范
变量长度:
变量名不要太长,尽量不超过5个单词,若太长可以使用单词缩写
变量缩写:
变量缩写可以采用两种缩写方案:
1.使用单词前几个字母,能表述含义即可,控制在3-5个字母(具体长度自定)。如:
医院:hosp
医生:doc
选项:opt
|
2.若页面内同时出现“文档”和“医生”那么doc会冲突,可以适当增加长度或变换单词来区分。如:
文档:docs
医生:doct
|
3.使用单词的重音字母,使人能看到字母联想到单词。如:
产品:pdt
配置:cfg
检查:chk
|
函数命名
操作类函数:
一般使用动词,配合各类形容词,大致如下:
1.纯动词。如:
save()
delete()
close()
|
2.动词+名词。如:
保存医生:saveDoc()
删除医院:delHosp()
创建产品:createPdt()
|
3.动词+形容词+名词。如
删除选中的医生:delSelectDoc()
追加一个临时医院:appendTempHosp()
保存所有产品:saveAllPdt()
|
获取数据类函数:
统一使用get
开头。如:
getDocList()
getDisablePdt()
getElementById(id)
|
从网络获取数据类函数:
统一使用load
开头。如:
获取省份数据:loadProvince()
根据省份ID获取市区数据:loadCityByProvinceId(pid)
根据市区ID获取县数据:loadCountyByCityId(cid)
|
load与get的区别个人认为在于,get更通用,可以用于代码内部的数据处理逻辑,load更倾向于从远程加载。
事件响应函数:
on+(动词/操作)+元素+事件名。如
点击保存按钮:onSaveBtnClick()
点击添加按钮:onAddBtnClick()
当是否可用复选框变更时:onIsEnableChkChange()
头像图片鼠标移入时:onHeaderImgMouseEnter()
|
也可以是on+元素+(动词/操作/用途)+事件名。如
onBtnSaveClick()
onChkIsEnableChange()
|
看个人习惯即可。
虽然看上去略繁琐,但通过函数名本身,就可以完整的定位到此函数的用途。例如onIsEnableChkChange
函数名:
- 看到
on
开头,知道这是一个响应界面操作事件的函数 - 看到
isEnable
,知道这是“是否可用”的功能的元素。 - 看到
chk
,知道这是一个复选框checkbox
元素的事件 - 看到末尾的
Change
,知道这是一个change
事件的响应函数 - 综上,看到命名,就可以联想到网页上有一个 名叫xxx是否可用的复选框,这是点击了这个复选框后的事件
变量命名
变量单词连接符:
不使用单词连接符,使用小驼峰式命名。如
btnSaveClick
|
布尔值类型变量:
统一使用is开头。如
是否可用:isEnable
是否选中:isCheck
是否删除:isDelete
|
集合类型变量:
统一使用List结尾。如
食品列表:foodList
医生列表:docList
已选产品列表:selectPdtList
|
数组循环体内临时变量:
若循环体代码量少,或仅一行lambda表达式,则可简写 doc
或d
, pdt
或p
循环体代码量大时,或嵌套循环时,尽量使用Item
结尾。如docItem
, pdtItem
不强制要求,仅为区分层级关系
字典变量:
统一使用Dic
(Dictionary)结尾,如
openWithDic
exeDumpDic
|
枚举集合:
统一使用Enum
(Enumeration)结尾。如
医生类型枚举:docTypeEnum
产品状态枚举:pdtStatusEnum
服务器状态码枚举:serverCodeEnum
|
枚举项:
建议使用全大写,使用下划线连接单词,与常量规则一致。如
服务器返回值失败:serverCodeEnum.ERROR
服务器返回值成功:serverCodeEnum.SUCCESS
|
jQuery变量:
建议使用$
开头,或J_
开头,风格统一即可。
$saveBtn
J_saveBtn
|
函数变量:
建议使用Fn
或Cb
结尾,标明此变量为函数指针。如
钩子函数:hookFn
响应回调函数:responseCb
回调函数:callback
|
常量:
统一使用全大写字母,单词用下划线连接。如
MAX_SIZE
TIME_OUT
|
类(Class)构造函数:
统一使用大驼峰式命名。如
ListView
DataTable
TableView
|
类私有属性:
如果未使用TypeScript
或其他强类型语言,即若没有使用带有访问修饰符(public
,private
等)的语言开发,应该通过变量名本身即可区分是私有属性还是公开属性。
私有属性以及私有函数,应统一以下划线开头。如
_data
_pdtList
_getData()
_setData()
|
目的在于给与类的使用者可以通过变量区分,哪些是可以使用的公开属性和方法,哪些不应该使用的私有属性以及不应该调用的私有方法。
组件事件命名:
1.统一使用on开头。如
onClick(e)
onSubmit(e)
|
2.关键流程类事件,应提供after事件和before事件,以onBefore和onAfter开头。如
准备提交前事件:onBeforeSubmit
提交后事件:onAfterSubmit
准备展开前事件:onBeforeExpand
删除后事件:onAfterDel
|
3.属性/状态变更类事件,应以on开头,changed结尾。如
check属性变更时事件:onCheckedChange
select属性变更时事件:onSelectedChange
产品状态变更时事件:onPdtStatusChange
|
代码建议
- 善用变量缓存
- 重复使用多次的字符串必须缓存
- 善用枚举变量,减少后期维护成本
- 类方法应全部挂载到原型对象
- 不应该使用类私有全局变量,应使用类静态变量
- 尽量减少闭包代码,以减少可能会出现的问题的概率
- 应坚持“先定义,后使用”的规范。以减少js默认的定义提升的坑
- 整个代码应该应只有一个入口函数,即创建一个init函数,来执行所有初始代码,而不是整篇代码随定义,随执行
- 事件绑定类函数应放在同一处执行,减少维护成本
- 善用#region 创建代码块,不同功能的代码归类,初始化类,事件绑定类,界面交互类,纯数据处理工具类等。
- 模块类文件,所有导出变量应全部定义在尾部。方便查阅
- 尽可能不创建全局变量,不注册全局事件,为后期方便转型为单页应用
- 尽量将代码纯数据逻辑与界面交互逻辑分开,方便后期写测试用例
- 尽量将所有变更定义放置在 文件/函数 内顶部
- 善用try catch和throw Error
- 不要在数组内存放不同类型的数据,一个数组应只存放一种数据类型变量,方便强类型识别与纠错
- 尽可能不要创建类数组变量
- 尽可能不使用eval、with
- 多写注释!推荐jsdoc风格注释,方便一键抽取注释生成代码文档
- 推荐使用flowjs或ts等类型描述语言来约束、规范、纠错和智能感知。
附:关于js中的对象、字典与枚举的关系
以上个人经验在组内分享时,有同学提出疑问:
为什么会有字典变量,以及枚举变量,这从本质上不都是Object对象么?
关于这个问题我是这么理解的,在js中确实对象是最强大的,任何在其他语言当中的类似对象的数据结构,在js里都可以是对象。但也正因为如此宽泛,让我们的使用过程中会产生一些疑惑或误解,才需要对各种的对象做分类。
所以回过头来再说对象,字典与枚举的关系。
他们的相同点:
他们都是键值对集合(KeyValuePair)
他们的Key都不能重复
他们的不同点:
对象:
对象的的Key可以是字符串类型或数值类型。如果同时包含这两种就类数组对象,比如document.getElementBy...系列函数的返回值:HTMLCollection
,再比如HTML元素的子元素集合:NodeList
,以及HTML元素的属性值:NamedNodeMap
,等都是类数组对象。
对象的Value的类型,可以是任意类型。而且是在一个对象变量中的Value都可以是任意类型,如JSON对象。
字典:
而字典的Key一定是字符串类型的(其他语言中不是,受限于js语言),字典的Value也可以任意类型,但在一个字典对象变量中的所有Value一定是相同类型,也就是说字典其实是个Object<string, TValue>
。
例:比如前面刚刚提到的HTML元素的attributes属性值:NamedNodeMap
,就是应该一个典型的字典对象:它属于Dictionary<string, Attr>
。
但是奇葩的是NamedNodeMap
也支持数组下标式访问,所以它同时也是一个List<Attr>
,在js里只能归结于他是类数组对象的范畴内了。
枚举:
而最后的枚举对象的范围会更小,枚举的值一般为基本数据类型,在其他语言中甚至只能是数值类型。
例如,定义一个枚举对象用于一组常量:
// 服务器接口返回值状态码枚举
var serverCodeEnum = {
SUCCESS : 0 ,
ERROR : 1 ,
XXXXX : 2 ,
XXXXX : 3 ,
}
|
TypeScript中的枚举变量
在TypeScript为了照顾js语言的日常使用,把enum关键字的编译后代码做成了双向访问的类数组对象。
也就是既可以用过名称获得数值,也可以通过数值获得名称。使用非常方便:
【TypeScript代码中的枚举】
enum ownerTypeEnum {
public = 0 ,
private
}
【编译为JS后的代码】
var ownerTypeEnum;
(function (ownerTypeEnum) {
ownerTypeEnum[ownerTypeEnum[ "public" ] = 0 ] = "public" ;
ownerTypeEnum[ownerTypeEnum[ "private" ] = 1 ] = "private" ;
})(ownerTypeEnum || (ownerTypeEnum = {}));
// 效果:
// ownerTypeEnum.private -> 1
// ownerTypeEnum[1] -> "private"
|