Javascript 编码规范 - 陈斌彬的技术博客

1.变量命名规范

变量名包括全局变量，局部变量，类变量，函数参数等等，他们都属于这一类。

基本规范：变量命名都以类型前缀+有意义的单词组成，单词首字母都需要大写。例如：sUserName，nCount。

前缀规范：每个局部变量都需要有一个类型前缀，按照类型可以分为：

    s：表示字符串。例如：sName，sHtml;

    n：表示数字。例如：nPage，nTotal;

    b：表示逻辑。例如：bChecked，bHasLogin;

    a：表示数组。例如：aList，aGroup;

    r：表示正则表达式。例如：rDomain，rEmail;

    f：表示函数。例如：fGetHtml，fInit;

    o：表示以上未涉及到的其他对象，例如：oButton，oDate;

例外情况：

1：作用域不大临时变量可以简写，比如：str，num，bol，obj，fun，arr。

2：循环变量可以简写，比如：i，j，k 等。

//不推荐
var checked = false;  
var check = function(){  
    return true;  
}  
/**  
some code  
**/
if(check){//可能将 checked 写成 check，由于不能很快速的发现check 是函数，造成逻辑错误  
    //do some thing  
}

//推荐
var bChecked = false;  
var fCheck = function(){  
    return true;  
}  
/**  
some code  
**/
if(bChecked){  
    // do some thing  
}  
if(fCheck()){  
    // do other thing  
}

全局变量以及常量规范

每个类定义都是在一个闭包函数中，除了在 window 下有类的定义而外，只允许有两种变量定义在全局，那就是全局变量和常量。

全局变量使用 g 作为前缀，定义在 window 下。例如 gUserName，gLoginTime。

某些作为不允许修改值的变量认为是常量，全部字母都大写。例如：COPYRIGHT，PI。常量可以存在于函数中，也可以存在于全局。

例子：

var userName = "dongua";  
function checkName(userName){  
    //存在函数参数userName以及全局变量userName,如果要比较两个值是否相等，必需写为  
    return window.userName == userName  
}

如果使用了全局变量的前缀，就十分清晰了。

2.函数命名规范

统一使用动词或者动词[+名词]形式，例如：fGetVersion()，fSubmitForm()，fInit(); 涉及返回逻辑值的函数可以使用 is，has 等表示逻辑的词语代替动词。

如果有内部函数，使用 __f +动词[+名词]形式，内部函数必需在函数最后定义。例如：

function fGetNumber(nTotal){  
    if(nTotal<100){  
  nTotal = 100;  
   }  
 return __fAdd(nTotal);    

 function __fAdd(nNumber){  
  nNumber++;  
  return nNumber;  
 }  
}  
alert(fGetNumber(30));//alert 101

对象方法实现

对象方法命名使用 f +对象类名+动词[+名词]形式;例如 fAddressGetEmail

事件响应函数

某事件响应函数命名方式为触发事件对象名+事件名或者模块名+触发事件对象名+事件名，例如：fDivClick()，fAddressSubmitButtonClick()

3.其他注意事项

1：所有命名最好使用英语表示。

2：所有变量名应该明确而必要，尽量避免不必要的容易混淆的缩写。

3：netease.events.mouse.Handler，而不是 netease.events.mouse.MouseEventHandler。

4：对应的方法应该使用对应的动词，例如：get/set, add/remove, create/destroy, start/stop, insert/delete, begin/end。

5：应该避免双重否定意义的变量，例如：bIsNotError, bIsNotFound，不可取。

6：变量应该在最小的范围内定义，并尽可能的保持最少的活动时间。

7：循环变量最好在循环中定义。例如 for(var i=0,m=10;i<m;i++){ do something}。

8：尽量避免复杂的条件语句，可以使用临时的boolean变量代替。

9：一定要避免在条件中执行语句，例如：if((i=3)>2){}，不可取。

10：不要在代码中重复使用相同意义的数字，用一个变量代替，比如 nTotal=100; num= total。

4.文件注释

/*!
 * jRaiser 2 Javascript Library
 * waterfall - v1.0.0 (2015-05-15T14:55:51+0800)
 * http://jraiser.org/ | Released under MIT license
 */

例2：

/*!
 * hx.com - v1.1 (2015-05-08T15:30:32+0800)
 * Copyright 2005-2015 hx.com
 */

如果文件内包含了一些开源组件，则必须在文件注释中进行说明。例如：

/*!
 * jRaiser 2 Javascript Library
 * sizzle - v1.9.1 (2015-05-15T10:07:24+0800)
 * http://jraiser.org/ | Released under MIT license
 *
 * Include sizzle (http://sizzlejs.com/)
 */

普通注释

普通注释是为了帮助开发者和阅读者更好地理解程序，不会出现在 API 文档中。其中，单行注释以 // 开头；多行注释以 /* 开头，以 */ 结束。普通注释的使用需遵循以下规定。

1.在单行注释符后留一个空格。例如：

// this is comment

2.在多行注释的结束符前留一个空格（使星号对齐）。例如：

/*

 */

3.不要把注释写在多行注释的开始符、结束符所在行。例如：

/* start

end */

改成：

/*
here is line 1
here is line 2
 */

4.不要编写无意义的注释。例如：

// 初始化value变量为0
var value = 0;

5.如果某段代码有功能未实现，或者有待完善，必须添加 TODO 标记，TODO 前后应留一个空格。例如：

// TODO 未处理IE6-8的兼容性
function setOpacity(node, val) {
    node.style.opacity = val;
}

文档注释

1.文档注释将会以预定格式出现在 API 文档中。它以 /** 开头，以 */ 结束，其间的每一行均以 * 开头（均与开始符的第一个 * 对齐），且注释内容与 * 间留一个空格。例如：

/**
 * comment
 */

2.文档注释必须包含一个或多个注释标签。

@module。声明模块，用法：

/**
 * 模块说明
 * @module 模块名
 */

例如：

/**
 * Core模块提供最基础、最核心的接口
 * @module Core
 */

3.@class。声明类，用法：

/**
 * 类说明
 * @class 类名
 * @constructor
 */

@class 必须搭配 @constructor 或 @static 使用，分别标记非静态类与静态类。

/**
 * 节点集合类
 * @class NodeList
 * @constructor
 * @param {ArrayLike<Element>} nodes 初始化节点
 */

4.@method。声明函数或类方法，用法：

/**
 * 方法说明
 * @method 方法名
 * @for 所属类名
 * @param {参数类型} 参数名 参数说明
 * @return {返回值类型} 返回值说明
 */

没有指定 @for 时，表示此函数为全局或模块顶层函数。当函数为静态函数时，必须添加 @static；当函数有参数时，必须使用 @param；当函数有返回值时，必须使用 @return。

@param。声明函数参数，必须与 @method 搭配使用。

当参数出现以下情况时，使用对应的格式：

[参数名]

参数有默认值：

[参数名=默认值]

@property。声明类属性，用法：

/**
 * 属性说明
 * @property {属性类型} 属性名
 */