Zving前端开发规范(JS部分)

1  引言

    好的编码规范可以尽可能的减少一个软件的维护成本;
    好的编码规范可以改善软件的可读性,可以让开发人员尽快而彻底地理解新的代码;
    好的编码规范可以最大限度的提高团队开发的合作效率;
    长期的规范性编码还可以让开发人员养成好的编码习惯,甚至锻炼出更加严谨的思维。

1.1  编写目的

  本文档旨在为Zving前端开发人员提供基本开发规范,提高其协作开发的水平;同时减少页面错误、提高系统健壮性。

 

1.2  使用环境及对象

  本规范可用于基于浏览器的B/S版软件项目的开发工作,还可用于目前正在进行开发的系统(包括ZCMS、ZAS、ZShop等)的后台页面。

  适用对象有:

  ●  UI设计人员;

  ●  开发编码人员;

  ●  模版编写人员。

 

1.3  开发工具

  ●   文本编辑器 Sublime Text 或 Visual Studio Code, http://www.sublimetext.com/ https://code.visualstudio.com/

  ●   语法检查工具 JSHint或JSLint,http://www.jshint.com   http://www.jslint.com

  ●   代码格式化工具 JS Beautifier,http://www.jsbeautifier.org/   http://code.google.com/p/jsbeautifier/。

  ●   代码压缩工具yuicompressor, http://developer.yahoo.com/yui/compressor/

 

1.4  编码

  web文件的“换行符类型”为“windows换行符-CR/LF”;编码为“GBK”或“UTF-8”(在需要与支持UTF-8的控件交互的情况下或在UTF-8版本里,使用“UTF-8”编码)。

 

2  Javascript编码规范

2.1  JS风格览表

结构

规则

备注

模块 首字母大写驼峰 不要使用多重语义(Never multiple words)
文件名 首字母大写驼峰 可带版本号或其它说明,如Dialog.compress.js
首字母大写驼峰  
公有方法 首字母小写驼峰  
公有属性 首字母小写驼峰  
私有方法/属性

'_'+首字母小写驼峰

 
侵入型私有属性

'__'+首字母小写驼峰

侵入型私有属性是指在别的对象上偷偷添加,给自己用的私有属性。需要尽量避免本类属性
变量 首字母小写驼峰  
常量

首字母小写驼峰或大写 (可以包含_)

 

2.2 命名规范

  ●  所有的变量名必须使用英文名称,不要使用拼音。

  ●  方法的命令必须为动词或者是动词短语:obj.getSomeValue()。

  ●  私有变量与属性必须使用混合名称(mixedCase)命名,并在前面加下划线(_)。例如:this._somePrivateVariable = statement。

  ●  变量如有较广的作用域(large scope),必须使用全局变量;此时可以设计成一个类的成员。相对的如作用域较小或为私有变量则使用简洁的单词命名。

  ●  公有变量必须清楚的表达其自身的属性,避免字义含糊不清,例如:MouseEventHandler,而非 MseEvtHdlr。

 

2.3 特殊命名规范

  ●  重复变量建议使用 "i"、 "j"、"k" (依次类推)等名称的变量。

  ●  补充用语必须使用补充词,例如: get/set、add/remove、create/destroy、start/stop、 insert/delete、begin/end、etc.等。

  ●  避免产生歧义的布尔变量名称,例如不要使用:isNotError、 isNotFound。

  ●  一些常用的变量命名或缩写:

 

2.4 命名空间

  为了适应复杂的应用环境,减少与其它系统协作时变量及方法名冲突,尽量避免声明全局变量、全局方法。可以使用命名空间来减少冲突,单纯的命名空间应该符合条件是小写字母且要有意义的英文单词。

 

2.5 注释

  鼓励按JsDoc的注释规范来写注释,以便可以通过JsDoc等工具自动生成API文档。

  在js文档的开头要写上此文档所实现的功能及实现思路(使用多行注释),保证不是原作者也可以接手开发工作。js文件里的变量或者方法,视情况加注释。

  方法体前用多行注释说明方法实现的目的并说明返回什么,方法体内重要代码及疑难代码可使用行内注释,重要代码后的注释主要是说明代码段的用处,疑难代码后的注释对逻辑进行解释。

  因解决浏览器兼容性而写的语句应该注释里要说明针对哪个浏览器所写。

 

2.6 主体代码风格

  主体代码风格可参考http://jsbeautifier.org/网站所提供的格式化工具格式化后所体现的风格(此主体代码风格指的是阅读和编辑时的风格,在系统发布时需要对js进行最小化压缩):

  ●  缩进的单位为四个空格(在编写代码时可用Tab缩进,编写完成后用格式化工具把Tab格式化成空格);

  ●  操作符之间建议用空格隔开;

  ●  “{”(左大括号)应该在复合语句起始行的结尾处;

  ●  “}”(右大括号)“{”的那一行的开头对齐;

  ●  “,”(逗号)后应跟一个空格,在对象定义、var语句中,“,”后面可换行,以方便阅读;

  ●  “;”(分号)在简单语句的结尾处时后面须跟换行,控制部分——如for语句——内的“;”后须跟一个空格;

  ●  单行的 IF - ELSE,WHILE 或者 FOR 语句也必须加入大括号,不过大括号及其间的语句可以使用紧缩形式,如:

  if (a < b) {a = b};

  ●  换行与缩进目的是为了代码更易读,所以只要符合逻辑,换行与缩进不仅可以在控件符后使用,也可以在运算符前使用。

 

2.7 变量声明及注释

  所有的变量必须在使用前进行声明。

  ●  使用有意义的英文单词作变量名,常用单词可进行缩写,如element或缩写为elem/ele/el,作用域越大的变量越要避免使用缩写;

  ●  普通变量名应该以小写字母开头,多个单词组合的变量名使用驼峰式写法,如 crrrentEntry;

  可以用&ldquo;_&rdquo;(下划线)开头暗示变量的私有性质,如var _idSeed = 0;

  可以用全部大写来暗示变量的全局性质(js没有常量),如:

  ●  每个变量的声明语句单独放在一行,尽量赋予初始值,并加上注释说明,示例如下:

  或

  ●  避免使用全局变量,使用闭包或命名空间来降低使用全局变量的可能,在变量作用域很广,需要在多个类中引用,这时需要使用到全局变量,可以用命名空间来管理,如

  ●  相关的变量集应该放在同一代码块中,非相关的变量集不应该放在同一代码块中。

  ●  变量应该尽量保持最小的生存周期,以提高执行效率。

  ●  使用循环语句时,尽量在循环条件里判断循环是否继续,以避免使用"break" 和 "continue" 语句,因为 continue 作为跳转语句,性能很低。

  ●  应避免在条件表达式中加入块。

 

2.8 方法声明及注释

  所有的方法必须在使用前进行声明。内方法的声明跟在var语句的后面:

  ●  使用有意义的英文单词作方法名,最好为动词短语,如 getSize(obj),setXY(x,y);

  ●  常用的动词有: get/set, add/remove, on/un, create/destroy, start/stop, insert/delete, begin/end, etc;

  ●  常用单词可进行缩写,如element或缩写为elem/ele/el,多个单词组合的变量名使用驼峰式写法,如 crrrentEntry;

  ●  普通方法以小写开头;必须与new共同使用的构造方法名应该以大写字母开头;

  ●  每个方法的声明之间空一行,方法前用多行注释说明方法的功能、参数类型等;

  有返回值则要说明返回什么,如果只是一个过程,亦要说明做了什么。

        示例如下:

  ●  因为函数可以同时返回多个不同(类型)的值,所以应每个返回值之后加入返回类型的注释。注释在行内注释即可,如果所有的返回值为同一类型,则指明返回的类型;如为多个不同的返回值,则标注返回类型为"mixed"。示例如下

  /**

  通过累加计数返回一个整数用于生成唯一id

  返回值类型: mixed

  **/

  ●  尽量减少全局方法的使用,可以用命名空间来管理,如:

2.9 文件

  ●  每一行不宜过长,写完一段代码后请使用http://jsbeautifier.org/ 提供的 JS Beautifier 方法来格式化JS代码,以保持代码风格的一致。

  ●  缩进请使用" "(制表位)。尤其不要制表位和空格混合使用。

  ●  js里的字符串,最外层尽量用',HTML里的字符串,最外层用"。

  document.getElementById('myId').innerHTML='<input name="price" value="10"/>';

  <input type=button value="ok" onclick="alert('ok!');"/>

 

2.10 布局

  ●  分号,能加的地方都加(基本上除了for、function、if、switch、try、 while外),防止因为这个问题导致压缩失败。

  ●  普通代码段 应该 看起来如下:

  ●  IF 语句 应该 看起来像这样:

  ●  FOR 语句 应该 看起来像这样:

  ●  WHILE语句 应该 看起来像这样:

  ●  DO ... WHILE 语句 应该 看起来像这样:

  ●  SWITCH 语句 应该 看起来像这样:

  ●  TRY ... CATCH 语句 应该 看起来像这样:

  ●  单行的 IF - ELSE,WHILE 或者 FOR 语句也 必须 加入括号:

 

2.11 特别注意

  ●  禁止扩展原生对象的原型,特别是Object.prototype。

  ●  尽量不要在if的条件部分使用赋值表达式,如果确实想要在if条件部分赋值,那么把它括在另一对括号中,如:if ((a = b)) { ... }

  ●  parseInt的第一个参数的第一个字符是0时,该字符串将被基于八进制而不是十进制求值。所以使用parseInt方法时,建议总是提供第二个参数来指明基于十进制求值。

  ●  因为javascript遵循二进制浮点数算术标准,所以不能正确地处理十进制的小数,因此在js中 0.1+0.2 不等于 0.3。但js中的整数运算是精确的,所以在需要精确浮点运算的时候,建议可以先乘以10的阶乘,使用整数部分运算,运算完后再除以10的阶乘。

 

2.12 其他建议

  ●  使用{}代替 new Object(),使用[] 代替 new Array();

  ●  某些情况下使用||或&&代替if,如 evt = evt || window.event;

  ●  避免在if和while语句的条件部分赋值。如 if(evt=window.event){}。

 

2.13 鼓励

  ●  使用命名空间来管理所有代码中的对象和变量;

  ●  使用闭包来隐藏临时变量、私有变量、私有方法;

  ●  建议在类型确定时使用===和!==运算符代替==和!=运算符。注意在ie下window!==window.parent。

 

2.14 ECMAScript 5 Strict Mode

  ES5的严格模式下,以下情况下会显式的报错;&hellip;&hellip;从现在开始养成严谨的编程习惯:

  ●  对未定义的变量赋值;

  ●  操作被设置为不可写,不可配置或不可扩充的属性;

  ●  删除变量,函数,参数;

  ●  在对象直接量里重复定义属性;

  ●  eval做关键字,在eval的字符串里定义变量;

  ●  覆写arguments;

  ●  使用arguments.caller和 arguments.callee(匿名函数必须具名才能引用自己);

  ●  (function(){ &hellip; }).call( null ); // Exception;

  ●  使用with。

 

3 基础类及工具类开发流程

  ●  主要参考extjs及dojo,因为这两个js框架都有比较多的组件:考虑了复杂的应用情况,同时也有较多的项目应用,我们需要的应用其中上都可以在这两个js框架中找到切实可行的解决方案。

 

4 组件开发流程

  ●  调研同类组件,整理成文档,分析列举出各种同类组件的优劣。主要参考extjs及dojo,因为这两个js框架都有比较多的组件:考虑了复杂的应用情况,同时也有较多的项目应用,我们需要的应用其中上都可以在这两个js框架中找到切实可行的解决方案。

  ●  确定组件要实现的功能,确定好组件的 public api.。

  ●  代码上,精简小巧,越小越好。功能上,遵循8/2原则,用 20% 的代码,开发出 80% 的常用功能即可,扩展上,适度灵活,提供扩展接口,让用户可以通过扩展,完成不常用的 20% 功能。

hackIE