[Web前端]Javascript编码规范

1 介绍

这篇文档的目的是说明Javascript的编码规范和他们的重要性。主要是为了开发者所使用，对大部分的项目管理者也有很大作用，使他们能看到清楚连贯的源代码。项目管理者应该鼓励他们的团队成员在写代码的时候遵循编码规范。

1.1 适用范围

Javascript编码规范是为client-side Javascript所指定的，但是也可适用于server-side Javascript编程，例如：nodejs

1.2 什么是编码规范

在写代码的时候所遵循特定的样式是为了编码规范。当然编码规范不可能完全理想化和覆盖所有可能的方面。无论什么时候如果有什么怀疑的地方还可以靠经验和所有的知识进行决定。

1.3 为什么需要编码规范

几乎没有一个软件在它的整个生命周期中只被它的原作者所维护，因此应用编码规范变得很有用，编码规范将使代码在最大程度上保持一致性，一致性使代码易读易于理解，易于开发易于维护，使在开发人员之间共享代码更方便。

长期优点：

 对于不同的项目中的人员的配置更灵活，因为所有的人员都使用相同的语言进行交流和编码；

 提高了软件的质量；

 因为清楚的代码节省了解决错误的时间；

 因为可重用和清楚的代码而节省了开发时间

1.4 感谢

这篇文档表达了Javascript编码规范，尽管Javascript和C#在大多数方面根本不相同，但是在某些方面还存在着类似之处，因此本文以Microsoft公司的C#编码规范作为基础，以防止出现几份不一致的编码规范

2 JavaScript文件

2.1 文件构成

JavaScript程序应该独立保存在后缀名为.js的文件中。

JavaScript代码不应该被包含在HTML文件中, 除非这是段特定只属于此部分的代码。在HTML中的JavaScript代码会明显增加文件大小,而且也不能对其进行缓存和压缩。

filename.js应尽量放到body的后面。这样可以减少因为载入script而造成其他页面内容载入也被延迟的问题。文件编码格式必须是UTF-8格式，防止乱码。

2.2 文件说明

所有的script文件都应该以下面的详细列出的注释块的格式开头：主题，作者，创建日期，文件名，描述说明，版权提示和文档的版本信息。

/*! Copyright (c) 2016 Kuangen (http://www.kuangen.com)

* ===========================================================================

* AUTHOR: Chart Nie.

* CREATION DATE: 2016-09-29 10:00.

* WORKFILE: Timeline.js

* DESCRIPTION: Create timeline for project, support to display the event as datetime desc

* ===========================================================================

* Version: 1.0

* DATE: 2016-09-29 10:00.

* AUTHOR: Chart Nie.

* DESCRIPTION: Init this control

* ===========================================================================

* Version: 1.1

* DATE: 2016-09-29 10:00.

* AUTHOR: Chart Nie.

* DESCRIPTION: Add datepicker control for Timeline.js

* ===========================================================================

*/

2.3 缩进

2.4 换行

超过100个字符长度的行总是无效的，即使是在一台只有很低分辨率(800*600)的终端上，也要尽可能的查看代码行是否产生水平的滚动条。当一个表达式不能够满足放在一行中的时候，根据以下原则拆分成几行：

• 操作符前换行；

• 逗号后换行；

• 相关逻辑放在一行，关系度低的换行；

• 以相同的起始位置对齐每一行；

例如：

if (this.newData[this.newData.length - 1].timespan == timespan

&& this.newData[this.newData.length - 1].date == this.data[i].date) {

timespanCount++;

}

else {

timespanCount = 1;

}

2.5 注释

有两种形式的注释可供使用：/…/和//… 注释通常意味着把某段代码注释起来或对某段代码特定实现的说明，注释应该能够用来为代码提供一个概括性的说明和一些代码本身不能表示出来的信息，注释应该指包括阅读和理解程序相关的内容。

Javascript代码有三种实现注释的形式：块注释、单行注释和行尾注释。推荐使用/…/进行注释，防止在压缩Javascript文件的时候注释掉正常代码。

2.5.1 块注释

块注释应该在前面使用一个空行与其他的代码分割开来：

/*

* This is a block comment.

* Each line is preceded by an asterisks.

*/

2.5.2 单行注释

一行就能写完的短注释：

if (condition) {

/* Short description about the following statments */

statements;

}

else {

/* Short description about the following statments */

statements;

}

2.5.3 尾注释

能够与代码共存于一行的非常短的注释：

if (condition) {

statements; /* Very short description */

} else {

statements; /* Very short description */

}

如果在一个代码块中需要不止一条短注释行，它们应该采用相同的缩进格式。

2.6 变量声明

• 所有的变量必须在使用前进行声明。JavaScript并不强制必须这么做，但是这么做可以让程序易于阅读，且也容易发现那些没声明的变量(它们会被编译成全局变量)。

• var语句放在函数的首部。

• 最好把每个变量的声明语句单独放到一行，并加上注释说明。所有变量按照字母排序。

var currentEntry; // 当前选择项

var level; // 缩进程度

var size; // 表格大小

• 尽量减少全局变量的使用。不要让局部变量覆盖全局变量。

2.7 函数声明

所有的函数在使用前进行声明。 避免使用内函数。

函数名与((左括号)之间不应该有空格。) (右括号)与 开始程序体的{(左大括号)之间应插入一个空格。函数程序体应缩进四个空格。 }(右大括号)与声明函数的那一行代码头部对齐，函数尾部加入;(分号)。

function outer(c, d) {

var e = c * d;

return e;

};

2.8 命名

1). 变量名应由26个大小写字母(A..Z,a..z),10个数字(0..9),和_(下划线)组成。避免使用国际化字符(如中文),因为它们不是在任何地方都可以被方便的阅读和理解。

2). 不要把_(下划线)作为变量名的第一个字符。

3). 变量名和方法命应以小写字母开头。

4). 全局变量所有字母必须全部大写。

5). 变量名必须具有一定的意义，如果需要缩写，也要保证缩写是大众所熟知的写法，例如：parameter 缩写为 para

6). 方法名以小写字母开头，首字母最好为动词。例如：

function closeLoading() {

this.element.find(“.timeline-box-loading”).hide();

};

2.9 语句

2.9.1 简单语句

每一行最多只包含一条语句。把;(分号)放到每条简单语句的结尾处。注意一个函数赋值或对象赋值语句也是赋值语句,应该以分号结尾。

2.9.2 复合语句

1). 复合语句是被包含在{ }(大括号)的语句序列。

2). 被括起的语句必须多缩进四个空格。

3). {(左大括号)应在复合语句其实行的结尾处。

4). }(右大括号)应与{(左大括号)的那一行的开头对齐

5). 大括号应该在所有复合语句中使用,即使只有一条语句,当它们是控制结构的一部分时, 比如一个if或者for语句。这样做可以避免以后添加语句时造成的错误。语句标示是可选的,只有以下语句必须被标示:while，do，for，switch。

2.9.2.1 return语句

一条有返回值的return语句不要使用( )(括号)来括住返回值。如果返回表达式,则表达式应与return 关键字在同一行,以避免误加分号错误， return语句前一行保留成空白行。

function getTimeline(option) {

var timeline = new Timeline(this, option);

return timeline.init();

};

2.9.2.2 if 语句

if语句应如以下格式:

1).

if(condition) {

statements;

}

2).

if(condition) {

statements;

} else {

statements;

}

3).

if(condition) {

statements;

}else if(condition) {

statements;

}else {

statements;

}

2.9.2.3 for语句

for语句应如以下格式:

for(initialization; condition; update) {

statements;

}

for(variable in object) if (filter) {

statements;

}

第一种形式的循环用于已经知道相关参数的数组循环。

第二种形式应用于对象中。

2.9.2.4 }while语句

while语句应如以下格式:

while(condition) {

statements;

}

2.9.2.5 do语句

do语句应如以下格式:

do{

statements;

}while(condition);

不像别的复合语句,do语句总是以;(分号)结尾。

2.9.2.6 switch 语句

switch语句应如以下格式:

switch(expression) {

case expression:

statements;

default:

statements;

}

每个 case与switch对齐。这可避免过分缩进。

每一组statements(除了default应以 break,return,或者throw结尾。不要让它顺次往下执行。

2.9.2.7 try语句

try语句应如以下格式:

try{

statements;

}catch(variable) {

statements;

}

try {
statements;

}catch(variable) {

statements;

}finally {

statements;

}

2.9.2.8 continue 语句

避免使用continue语句。它很容易使得程序的逻辑过程晦涩难懂。

2.9.3 with 语句

不要使用with语句。

2.9.4 空白

用空行来将逻辑相关的代码块分割开可以提高程序的可读性。

空格应在以下情况时使用:

• 跟在((左括号)后面的关键字应被一个空格隔开。

while(this.newData.length >= max) {

• 函数参数与((左括号)之间不应该有空格。这能帮助区分关键字和函数调用。

• 所有的二元操作符,除了.(点) 和((左括号)和 [(左方括号)应用空格将其与操作数隔开。

• 一元操作符与其操作数之间不应有空格,除非操作符是个单词,比如typeof。

• 每个在控制部分,比如for 语句中的; (分号)后须跟一个空格。

• 每个,(逗号)后应跟一个空格。

2.9.5 {} 和[]

使用{}代替new Object()。使用[]代替new Array()。

当成员名是一组有序的数字时使用数组来保存数据。当成员名是无规律的字符串或其他时使用对象来保存数据。

2.9.6 逗号操作符

避免使用逗号操作符,除非在特定的for 语句的控制部分。(这不包括那些被用在对象定义，数组定义，var语句和参数列表中的逗号分隔符。)

2.9.7 作用域

在JavaScript中块没有域。只有函数有域。不要使用块,除非在复合语句中。

2.9.8 赋值表达式

避免在if和while语句的条件部分进行赋值。

if(a = b) {

是一条正确语句?或者

if(a == b) {

才是对的?避免这种不容易判断对错的结构。

===和!==操作符。

使用===和!==操作符会相对好点。==和!=操作符会进行类型强制转换。 特别是, 不要将==用于与错值比较( false,null,undefined,“”,0,NaN)。

2.9.9 加号和减号

小心在+后紧跟+或++。这种形式很容易仍人迷惑。应插入括号以便于理解。

total = subtotal + +myInput.value;

最好能写成

total = subtotal + (+myInput.value);

这样+ +不会被误认为是++。