JavaScript编码规范.docx
《JavaScript编码规范.docx》由会员分享，可在线阅读，更多相关《JavaScript编码规范.docx（36页珍藏版）》请在冰点文库上搜索。
JavaScript编码规范
JavaScript编码规范
2016年02月18日
规范基本信息表：
规范简称：
JavaScript编码规范
规范版本号：
1.0
规范修订日期：
2016-02-18
本规范位置：
先前版本位置：
规范制定组织：
规范制定牵头人：
王军锋
规范校订人：
JavaScript编码规范
1 概要
1.1 规范摘要
本规范主要目的是定义基于JavaScript编码的总体规范，确保编码的规范性，提高程序的可维护性。
通过遵循共同的编码规范，程序开发人员可以保持代码一贯的风格，提高代码编写的可读性和使用的一贯性。
1.2 背景
1.3 现状
1.4 相关工作说明
1.5 规范声明
2 适用范围
3 引言
3.1 词汇表
首选术语
相关术语
3.2 格式约定
3.3 文件引用
《ECMAScript-262标准》。
《JavaScript权威指南V5》。
《JavaScript高级程序设计V2》。
《JavaScript高性能》。
《GoogleJavaScript开发规范》。
4 需求
5 规范正文
5.1 排版规范
文件结构
JavaScript文件按如下顺序组织各元素：
序号
元素
说明
1
版权、版本声明
以注释的方式进行声明
2
总体注释
在注释中总体介绍该文件实现的功能；
对如何使用这些功能给出指导性意见；
给出使用示例；
指出注意事项；
罗列依赖的其它JavaScript文件；
注明：
第一作者、第二作者…。
3
程序内容
缩进排版
以4个空格为一个缩进单元，避免使用Tab制表符。
【示例】：
functiongetUser（id）{
if（!
id）{
thrownewError（“”）;
}
}
行排版
一行的字符不建议超过120个字符，一行过多的字符会影响查看程序的效率。
如果一段描述不能放在一行中，依据下列规则将其拆分成多行：
1）从分隔符（比如空格）后换行;
2）在运算符之前换行;
3）不拆分完整的单词；
4）换行后如果需要缩进则不应缩进超过行中。
【示例】：
if（（condition1&&condition2）||（condition3&&condition4）
||!
（condition5&&condition6））{
}
空白的使用
函数之间空1行，get/set方法除外。
【示例】：
functioncreateUser（）{
}
functiondestoryUser（）{
}
functiongetUser（）{
returnthis.user;
}
functionsetUser（user）{
this.user=user;
}
代码逻辑段之间空一行。
【示例】：
functiongetUser（id）{
//判断参数id的合法性
if（!
id）{
thrownewError（“”）;
}
//根据参数id查找user对象
findUser（id）;
}
语句
表达式语句
表达式语句以分号结束。
【示例】：
vari=0;
alert（”提示信息”）;
Math.cos（x）;
复合语句
复合语句是包含在花括号中的一个语句或者语句块，复合语句遵循如下排版规则：
1）左花括号”{”位于复合语句起始行的行尾,右大括号"}"应另起一行并与复合语句首行对齐；
2）花括号中的语句缩进一个层次（4个空格）。
返回语句
【示例】：
{
varx=0;
}
if-else语句
if-else语句总是用"{"和"}"括起来,避免发生错误。
【示例】：
if（expression1）{
statement1;
}elseif（expression2）{
statement2;
}else{
statement3;
}
for语句
【示例】：
for（initialize;test;increment）{
statement;
}
一个空的for语句：
在初始化，条件判断，更新子句中完成，应该具有如下格式：
【示例】：
for（initialize;test;increment）;
for-in语句
【示例】：
for（variableinobject）{
statement;
}
while语句
【示例】：
while（expression）{
statement;
}
do-while语句
【示例】：
do{
statement;
}while（expression）;
switch语句
【示例】：
switch（expression）{
casevalue1:
statement;
break;
casevalue2:
statement;
break;
default:
statement;
break;
}
当一个执行完一个case后需要顺着往下执行（即没有break语句）时，通常应在break语句的位置添加注释。
上面的示例代码中就包含注释/**/。
try-catch-finally语句
【示例】：
try{
statement;
}catch（e）{
statement;
}finally{
statement;
}
5.2 注释规范
注释位置
1）函数和方法：
每个函数和方法都应该包含一个注释，描述其目的和用于完成任务所可能使用的算法，基于参数类型、参数可选择值、返回值；
2）大段代码：
用于完成单个任务的多行代码应该在前面填加描述任务的注释；
3）复杂的算法：
在使用复杂算法的代码处添加注释，以便下次查阅代码时帮助理解；
4）Hack：
因为不同的浏览器存在差异，JavaScript以便会包含一些hack，需要在这些hack的代码前添加注释，以便提醒代码维护者。
块注释
块注释以”/**”开头或者”/*”开头，以”*/”结尾，Doc注释以”/**”开头，比如：
注释在JavaScript文件开头、函数、变量上的注释通常会用于生成doc文档；非Doc注释的多行注释以”/*”开头。
在Doc注释中需要注明类型，常见的类型包括：
Object、Array、Function、Number、String、Boolean、Math等，类型注释规则如下表：
符号
举例
说明
{类型}
{Object}
对象类型
{|}
{Number|Object}
Number或者Object类型
{!
}
{!
Object}
非对象类型
{?
}
未知类型
{*}
所有类型
注：
在注释中的Number包装类型代指Number类型或者number基本类型，其它包装类型类似。
Doc注释举例：
【示例】：
/**
*{Object}用户对象
*/
varuser={};
/**
*通过用户对象获取用户名称
*@param{Object}user用户对象
*@return{String}用户名称
*/
functiongetUserName（user）{
/*
*如果user为null，则该方法会出现异常，需要对输入参数user进行可靠性校验
*需判断user变量是否是user对象
*/
returnuser.name;
}
//如果没有返回值，可以不用在注释中写@return
/**
*设置用户名称
*@param{Number}age用户名称
*/
functionsetUserName（name）{
this.name=name;
}
单行注释
单行注释，以”//”开头，非Doc注释时使用。
【示例】：
functiongetUserName（user）{
//返回用户名称
returnuser.name;
}
JavaScript文件注释
在文件头位置对JavaScript文件进行注释，说明该文件的版权、版本等信息。
【示例】：
/**
*本文件是$项目名称V$VERSION的一部分
*Copyright（C）2000-2011公司名称
*Provider:
组织名称
*联系方式：
*版权说明：
*/
函数/方法注释
【示例】：
/**
*通过用户对象获取用户名称
*@param{Object}user用户对象
*@return{String}用户名称
*/
functiongetUserName（user）{
returnuser.name;
}
变量/属性注释
【示例】：
/**
*{Object}用户对象
*/
varuser={};
5.3 声明规范
变量
局部变量和全局变量均使用var关键字进行声明。
【示例】：
varname=“”;
在同一作用域（在JavaScript中共三种作用域：
全局作用域、局部作用域、嵌套局部作用域）的开头位置声明变量，避免出现重复声明变量的问题,for、for-in语句的循环变量除外。
【示例】：
//全局变量
varglobalV=“global”;
functionprintUserProperty（）{
//局部变量
varusers=[{name:
”用户1”},{name:
”用户2”}];
//for语句变量i,user
for（vari=0,user;user=users[i];i++）{
printUserProperty（user）;
}
functionprintUserProperty（user）{
//嵌套局部变量
varcount=10;
//for-in语句变量prop
for（varpropinuser）{
alert（prop）;
}
}
}
声明全局变量、对象属性、函数参数时需注释变量类型或者赋初值（通过初值确定变量类型），由于局部变量是在代码块内部定义，作用范围有限，因此不做要求。
【示例】：
//全局变量
varisSuccess=false;//推荐的布尔类型初始值：
false
varcount=-1;//推荐的number类型初始值：
-1
varname=“”;//推荐的字符串类型初始值：
“”
varuser=null;//推荐的对象类型初始值：
null
varobj={
//对象属性
name=“”
};
//函数参数
/**
*设置名称
*@param{string}name名称
*@return
*/
functionsetName（name）{
}
可以一次声明多个变量，变量之间用“,”分隔，如果变量有初值或者注释则需换行，换行后与上一行的第一个变量左对齐。
【示例】：
varname,password,age,sex;
//有注释或者初值应换行
varname,password,
age,//年龄
sex=“男”;
采用直接量的方式声明对象，提高对象声明的代码可读性，对象属性和方法行前空4格,对象的属性或者方法以“，”分隔，最后一个属性或者方法不应出现“，”,属性之间不空行，方法之间空两行。
【示例】：
//优
varuser={
id:
””,
name：
“”，
setName:
function（name）{
this.name=name;
},
getName:
function（）{
returnthis.name;
}
}
//劣
varuser=newObject（）;
user.id=“”;
user.name=“”;
user.setName=function（name）{
this.name=name;
}
user.getName=function（）{
returnthis.name;
}
采用直接量的方式声明数组，尽量不采用构造函数，避免错误。
【示例】：
//优
vararr=[x1];
//劣
//如果x1是正整数，则数组长度=x1
//如果x1是非正整数的number，则会出现error
//如果x1是非number类型，数组长度=1,x1将作为数组的一个内容
vararr=newArray（x1）;
函数
使用function关键字声明函数。
【示例】：
functiongetUser（）{
}
//函数变量
vargetUser=function（）{
}
函数参数之间用“,”分隔。
【示例】：
functioncreateUser（id,name,password）{
}
函数代码行前空4格。
【示例】：
functiongetUser（）{
return{name:
”用户”};
}
相邻函数之间空2行
【示例】：
functionsetUser（）{
}
functionsetUser（user）{
}
匿名函数的右花括号右端不应有代码，左花括号左端不应有代码。
【示例】：
excute（'whatever',function（p1,p2）{
}）;
在