JS编码规范

JavaScript编码规范 1.说明 本规范适用于汉捷机械部件（常州）有限公司信息技术部，为公司的系统开发提供标准及约定，有助于软件开发人员快速掌握JS的编码规则，能够快速的融入到团队开发中，使用团队开发的效率大大提高。

2.命名规范

3.1 基础命名规范 1. 所有变量必须是有意义的英文，禁止使用拼音，如错误的写法： paifuwu(); fucusTa(); 2. 变量允许使用公认英文缩写，如： showMsg(); getXML(); 3. 类命名必须是驼峰式，如： var foo = new MyClass(); 4. 常量必须所有单词大写，并且每个单词间加下划线，如： var BITMAP_FLAG = 777; 5. 枚举类型时，枚举的命名必须有意义，枚举和枚举成员必须以驼峰式或大写： var NodeTypes = { Element : 1, DOCUMENT: 2 } 6. 常量和枚举必须在最前端定义，脚本合并时注意，必须把常量与枚举定义的文件放在文件列表的第一位 7. 变量内的简写单词不能全大写，如： XmlDocument strHtml 8. 函数开头必须是有意义的动词或动词短语，如： getSize() setSize() isTrue() 9. 私有类的变量属性成员必须使用混合式命名，并前面下下划线，如： _foo _height _getSize() 10. 临时的全局变量放到一个全局的哈希表里，方便变量回收 11. 大括号前面不能有换行符： //正确的写法： if (true) { } //错误的写法： if (true) { }

3.2 高级命名规范 1. 前面加 “is” 的变量名应该为布尔值，亦可使用 “can” “has” “should” 2. 前面加 ”str” 的变量名应该为字符串 3. 前面加 “arr” 的变量名应该为数组 4. 前面加 “num” 或 “count” 的变量名应该为数字 5. “o” 作为局部变量或参数，表示为 Object 6. “ e” 作为局部变量或参数，表示为 Event 7. “el” 作为局部变量或参数，表示为 Element 8. 能缩写的单词尽量缩写 9. 避免产生令人误解的布尔值：isNotNumber isNan 10. 处理错误的变量，必须在后面跟着 “Error” 11. 尽量做有意义的代码折行，不要让一行代码过长。 (HTML 字符串除外) 12. 逗号（ , ） 建议使用空格隔开。 13. 操作符建议使用空格隔开（包括三元操作符）。var i = k < 0 ? 1 : 0;

3.语法规范

4.1 变量 1. 保留字以及特有的 dom 属性不能作为变量名 2. 公有变量必须清楚的表达其自身的属性，避免字义含糊不清 3. 不允许频繁使用 previousSibling 和 nextSibling 4. 不允许使用多次 parentNode 对变更频繁的页面做精确的 dom 定位 5. 重复变量建议使用 "i", "j", "k" （依次类推）等名称的变量(全世界公认) 6. 所有全局变量必须初始化

4.2 函数 1. 初始化用的函数必须使用“init”开头，如果一个页面只有初始化可以单独使用 init() 2. 基类可以在明确描述其属性的前提下，缩减其命名 3. 函数调用和方法避免使用空白 4.3 参数 1. 多个可选参数必须以 Hash 表的方式传入 function foo(a,b,c,opt); //其中 a,b,c 都是 foo 的必选参数，opt 是可选参数 2. 不允许必选参数之间夹带可选参数 语法布局参考 1. 普通代码段应该看起来如下： while(!isDone){ doSomething(); isDone = moreToDo(); } 2. if 语句应该看起来像这样： if(someCondition){ statements; }elseif(someOtherCondition){ statements; }else{ statements; } 3. for 语句应该看起来像这样： for(initialization; condition; update){ statements; } 4. while 语句应该看起来像这样： while(!isDone){ doSomething(); isDone = moreToDo(); } 5. do ... while 语句应该看起来像这样： do{ statements; }while(condition); 6. switch 语句应该看起来像这样： switch(condition){ case ABC: statements; // fallthrough case DEF: statements; break; default: statements; break; } 7. try ... catch 语句应该看起来像这样： try{ statements; }catch(ex){ statements; }finally{ statements; } 8. 单行的 if – else， while 或者 for 语句也必须加入括号： if(condition){ statement;} while(condition){ statement;} for(intialization; condition; update){ statement;}

4.注释规范 脚本注释方案采用业界标准的JSDoc toolkit的注释风格。规范注释可以更好地提高代码的可读性以及接口文档的输出。

4.1注释约定 1. /** … */ 表示该段注释使用 JSDoc 规范 2. /* … */ 表示内部注释，通常用来做详尽的功能的实现描述 3. // 表示行注释，行注释可以在被注释对象的上一行和行末。 不能在换行处使用 4. 关于参数的注释可以采用内嵌的方式进行注释参数期望的类型 function getPerson(/**String*/ name) /**Array*/ { }

4.2常用注释关键字列表 a) 脚本文件头注释规范 模版参考如下: /** * @fileOverview 脚本文件描述 * @author , QZFL Team * @version * @updateDate */ b) @example

命名空间方法集的方法必须加上接口使用方法的案例，例如 /** * 根据ID 获取dom 对象 * @example * var _div1 = QZFL.dom.getById("div1"); */ QZFL.dom.getById = function() { //code here } 类必须在构造函数定义函数上添加完整的@example，代码范例需要加上常用接口使用案

例。 c) @constructor 构造函数必须在注释中申明其类型 d) @returns {returnType} returnDescription 如果函数有返回值，必须注明其返回的类型和描述 /** * @returns {Array} 返回物品列表 */ function getItems(){ var _items = []; //code here return _items; } e) @namespace

方法集对象均作为命名空间对象，例如 /** * @namespace QZFL 方法核心库之一，负责对浏览器DOM 操作提供基础的支持 */ QZFL.dom = {} f) @deprecated

即将回收的接口，不建议使用接口必须声明 @deprecated g) @private 私有接口必须声明，避免私有接口出现在文档中 h) @requires 有其他库依赖的接口和组件必须声明所依赖的接口名称 /** * @requires QZFL.dialog */ QZFL.widget.confirm = {} i) @type

所有变量名必须需要使用 @type来声明变量的类型 /** * 对象id 号 * @type number */ this. id = id; j) @event

事件接口必须使用 @event来声明其作用 /** * 当动画停止后 * @event */ this.onMotionStop = QZFL.emptyFn; k) @default

带默认参数的变量，需要声明起默认值，例如 /** * @default "Undefined" */ this.title = title || "Undefined"; l) @ignore

当变量或函数不希望在输出文档被获知到，可以使用 @ignore 忽略 /** * @ignore */ this.title = title || "Undefined"