JavaScript编码规范

1. 目的

本规范的目的是使本组织能以标准的、规范的方式设计和编码。经过创建编码规范，以使每一个开发人员养成良好的编码风格和习惯；并以此造成开发小组编码约定，提升程序的可靠性、可读性、可修改性、可维护性和一致性等，增进团队间的交流，并保证软件产品的质量。

 

2. 适用范围

本规范适用于XXXXX有限公司技术部全部软件开发人员，在整个软件开发过程当中必须遵循此规范。

 

3. 版权声明

²  本文档为共享文档，不限转载，但请保持本文档的完整性

²  您能够修改本文档以符合您或组织、公司等之实际，但请在文档中保持对本文档的引用和说明。

²  未经产品开发中心受权，任何我的、组织或单位不得将本文档用于书面发表、转载、摘录等，亦不得用于其余商业行为。

²  本人及本组织不承担任何因使用、参考本文档等而致使的任何可能责任或连带责任。

 

4. 参考资料

²  《Sun Java语言编码规范》(Java Code Conventions)

 

5. 概述

这是一套适用于JavaScript程序的编码规范。它基于Sun的Java程序编码规范。但进行了大幅度的修改, 由于JavaScript不是Java。

对于代码，首要要求是它必须正确，可以按照设计预约功能去运行；第二是要求代码必须清晰易懂，使本身和其余的程序员可以很容易地理解代码所执行的功能等。然而，在实际开发中，每一个程序员所写的代码却常常自成一套，不多统一，致使理解困难，影响团队的开发效率及系统的质量等。所以，一份完整并被严格执行的开发规范是很是必须的，特别是对软件公司的开发团队而言。

最根本的原则：

代码虽然是给机器运行的，但倒是给人读的！

运用常识。当找不到任何规则或指导方针，当规则明显不能适用，当全部的方法都失效的时侯，运用常识并核实这些基本原则。这条规则比其它全部规则都重要。常识是必不可少。

当出现该状况时，应当及时收集并提交，以便对本规范进行修改。

 

6. 规范要求

 

6.1.  保证代码压缩后不出错

对于大型的JavaScript项目，通常会在产品发布时对项目包含的全部JavaScript文件进行压缩处理，好比能够利用Google Closure Compiler Service对代码进行压缩，新版jQuery已改用这一工具对代码进行压缩，这通常会去掉开发时写的注释，除去全部空格和换行，甚至能够把原来较长的变量名替换成短且无心义的变量名，这样作的目的是加快文件的下载速度，同时也减少网站访问带来的额外数据流量，另外在代码保护上也起到了一点点做用，至少压缩后的代码即便被还原仍是没那么容易一下读懂的。

要想代码能正确经过压缩，通常要求语句都要以分号正常结束，大括号也要严格结束等，具体还要看压缩工具的要求。因此若是一开始没有按标准来作，等压缩出错后再回去找错误那是浪费时间。

 

6.2.  保证代码能经过特定IDE的自动格式化功能

通常较为完善的开发工具（好比Aptana Studio）都有代码“自动格式”化功能，这一功能帮助实现统一换行、缩进、空格等代码编排，你能够设置本身喜欢的格式标准，好比左大括号{是否另起一行。达到这个要求的目的在于方便你的开发团队成员拿你代码的一个副本用IDE自动格式化成他喜欢或熟悉的风格进行阅读。你同事须要阅读你的代码，多是由于你写的是通用方法，他在其它模块开发过程当中也要使用到，阅读你的代码能最深刻了解方法调用和实现的细节，这是简单API文档不能达到的效果。

 

6.3.  使用标准的文档注释

这一要求算是最基本的，这有利于在方法调用处看到方法的具体传参提示，也能够利用配套文档工具生成html或其它格式的开发文档供其余团队成员阅读，你能够尝试使用jsdoc-toolkit。若是你自动生成的API是出自一个开放平台，就像facebook.com应用，那么你的文档是给天下全部开发者看的。

另外编写完整注释，也更方便团队成员阅读你的代码，经过你的参数描述，团队成员能够很容易知道你编写的方法传参与实现细节。固然也方便往后代码维护，这样即便再大的项目，过了很长时间后，回去改点东西也就不至于本身都忘记了当时本身写的代码是怎么一回事了。

 

6.4.  使用规范有意义的变量名

使用规范有意义的变量名能够提升代码的可读性，做为大项目开发成员，本身写的代码不只仅要让别人容易看懂。开发大项目，其实每一个人写的代码量可能都比较大，规范命名，往后本身看回本身的代码也显的清晰易懂，好比往后系统升级或新增功能，修改起代码来也轻松多了。若是到头发现本身当初写的代码如今看不太懂了，那还真是天大的笑话了。

固然，使用有意义的变量名也尽可能使用标准的命名，好比像这里：var me = this也许没有var self = this好，由于self是Python中的关键字，在Python中self就是一般语言this的用法。再看下面一个例子，加s显然比没有加来的科学些，这样能够知道这个变量名存的是复数，多是数组等：

var li = document.getElementsByTagName('li')  

var lis = document.getElementsByTagName('li') 

 

6.5.  不使用生偏语法

JavaScript做为一门动态脚本语言，灵活性既是优势也是缺点，众所周知，动态语言不一样层次开发人员对实现一样一个功能写出来的代码在规范或语法上会存在较大的差异。无论怎么样，规范编码少搞怪，不把简单问题复杂化，不违反代码易读性原则才是你们应该作的。

好比这语句：typeof(b) == 'string' && alert(b)应该改成：if (typeof(b) == 'string') alert(b)，像前面那种用法，利用了&&运算符解析机制：若是检测到&&前语句返回false就再也不检测后面语句，在代码优化方面也有提到把最可能出现的状况首先判断，像这种写法若是条件少还好，若是条件较多并且语句也长，那代码可读性就至关差。

又好比：+function(a){var p = a;}( 'a')应该改成：(function(a){var p = a;})( 'a')，其实function前面的+号与包含function的()括号做用是同样的，都是起运算优先做用，后者是常见且容易看明白的防止变量污染的作法，好比好些流行JavaScript框架就是采用后面这种方式。

再说个下降代码可读性的例子，如：functiongetPostionTxt(type){return type == 2 ? "野外" : (type == 3 ? "商城" : (type == 4 ? "副本" : null));}应该改为：function getPostionTxt(type){vartypeData={"2":"野外","3":"商城","4":"副本"};if (typeData[type]) return typeData[type]; else return null;}。若是type是从0开始不间断的整数，那么直接使用数组还更简单，这种结果看起来就清晰多了，看到前面那种多层三元表达式嵌套头不晕吗。

 

6.6.  不在语句非赋值地方出现中文

语句中不该该出现中文我想通常人都知道，虽然这样作不影响程序运行，可是显然有背行业标准要求，固然咱们也不是在使用“易语言”作开发。关于这一个问题，我原本不想把它拿出来讲的，但我确实遇到有人这样作的，也不知道是否是由于他的英语实在太烂了，至少还能够用拼音吧，另外寻求翻译工具帮忙也不错的选择。我举例以下，像如下写法出如今教学中倒还能够理解：

this.user['名字'] = '张三'　或者　this.user.名字 = '张三'

 

6.7.  明肯定义函数固定数量的参数

固定数量参数的函数内部不使用arguments去获取参数，由于这样，你定义的方法若是包含较多的脚本，就不能一眼看到这个方法接受些什么参数以及参数的个数是多少。好比像下面：

var $ = function(){return document.getElementById(arguments[0]);}

应该改为：

var $ = function(elemID){return document.getElementById(elemID);}

 

6.8.  没必要热衷动态事件绑定

虽然知道事件能够动态绑定，好比使用addEventListener或者使用jQuery的bind方法，也知道采用动态事件绑定可让XHTML更干净，可是通常状况下我仍是建议直接把事件写在DOM节点上，我认为这样可使代码变得更容易维护，由于这样作，咱们在查看源代码的时候就能够容易地知道什么Element绑定了什么方法，简单说这样更容易知道一个按钮或连接点击时调了什么方法脚本。

 

6.9.  下降代码与XHTML的耦合性

不要过于依赖DOM的一些内容特征来调用不一样的脚本代码，而应该定义不一样功能的方法，而后在DOM上调用，这样无论DOM是按钮仍是连接，方法的调用都是同样的，好比像下面的实现显然会存在问题：

function myBtnClick(obj)  

{  

if (/肯定/.test(obj.innerHTML))   

alert('OK');  

else if (/取消/.test(obj.innerHTML))   

alert('Cancel');  

else   

alert('Other');  

} 

<a herf="javascript:;" onclick="myBtnClick(this)">肯定</a>

<a herf="javascript:;" onclick="myBtnClick(this)">取消</a> 

上面例子其实在一个函数内处理了两件事情，应该分红两个函数，像上面的写法，若是把连接换成按钮，好比改为这样：

<input type="button" onclick="myBtnClick(this)" value="肯定" />，

那么myBtnClick函数内部的obj.innerHTML就出问题了，由于此时应该obj.value才对，另外若是把按钮名称由中文改成英文也会出问题，因此这种作法问题太多了。

 

6.10. 一个函数应该返回统一的数据类型

由于JavaScrip是弱类型的，在编写函数的时候有些人对于返回类型的处理显得比较随便，我以为应该像强类型语言那样返回，看看下面的两个例子：

function getUserName(userID)  

{  

if (data[userID])  

return data[userID];  

else 

return false;  

} 

应该改成：

function getUserName(userID)  

{  

if (data[userID])  

return data[userID];  

else 

return "";  

} 

这个方法若是在C#中定义，咱们知道它准备返回的数据类型应该是字符串，因此若是没有找到这个数据咱们就应该返回空的字符串，而不是返回布尔值或其它不合适的类型。这并无影响到函数未来的调用，由于返回的空字符串在逻辑判断上可被认做“非”，即与false同样，除非咱们使用全等于“===”或typeof进行判断。

 

6.11. 规范定义JSON对象，补全双引号

使用标准确定是有好处的，那么为何仍是有人不使用标准呢？我想这多是懒或习惯问题。也许还会有人跟我说，少写引号能够减轻文件体积，我认为这有道理但不是重点。对于服务器返回的JSON数据，使用标准结构能够利用Firefox浏览器的JSONView插件方便查看（像查看XML那样树形显示），另外你若是使用jQuery作开发，最新版本jQuery1.4+是对JSON格式有更高要求的，具体的能够本身查阅jQuery更新文档。好比：{name:"Tom"}或{'name':'Tom'}都应该改为{"name":"Tom"}。

 

6.12. 不在文件中留下将来肯定再也不使用的代码片断

当代码调整或重构后，以前编写的再也不使用的代码应该及时删除，若是认为这些代码还有必定利用价值能够把它们剪切到临时文件中。留在项目中不只增长了文件体积，这对团队其它成员甚至本身都起到必定干扰做用，怕未来本身看回代码都搞不懂这方法是干什么的，是否有使用过。固然能够用文档注释标签@deprecated把这个方法标识为不推荐的。

 

6.13. 不重复定义其余团队成员已经实现的方法

对于大型项目，通常会有部分开发成员实现一些通用方法，而另一些开发成员则要去熟悉这些通用方法，而后在本身编写模块遇到有调用的须要就直接调用，而不是像有些开发者喜欢“单干”，根本不会阅读这些通用方法文档，在本身代码中又写了一遍实现，这不只产生多余的代码量，固然也是会影响团队开发效率的，这是没有团队合做精神的表现，是重复造轮子的悲剧。

好比在通用类文件Common.js有定义function $(elemID){return document.getElementById(elemID)}那么就不该该在Mail.js中再次出现这一功能函数的重复定义，对于一些复杂的方法更应该如此。

 

6.14. 调用合适的方法

当有几个方法均可以实现同类功能的时候，咱们仍是要根据场景选择使用最合适的方法。下面拿jQuery框架的两个AJAX方法来讲明。若是肯定服务器返回的数据是JSON应该直接使用$.getJSON，而不是使用$.get获得数据再用eval函数转成JSON对象。若是由于本次请求要传输大量的数据而不得以使用$.post也应该采用指定返回数据类型（设置dataType参数）的作法。若是使用$.getJSON，在代码中咱们一眼能看出本次请求服务器返回的是JSON。

舒适提示：jQuery1.4后，若是服务器有设置数据输出的ContentType，好比ASP.NET C#设置 Response.ContentType = "application/json"，那么$.get将与$.getJSON的使用没有什么区别。

 

6.15. 使用合适的控件存储合适的数据

曾发现有人利用DIV来保存JSON数据，以待页面下载后未来使用，像这样：<div id="json">{ "name":"Tom"}</div>，显然这个DIV不是用来界面显示的，若是非要这样作，达到使用HTML文件进行数据缓存的做用，至少改为用隐藏域来存这数据更合理，好比改为：<input type="hidden" value=" { "name":"Tom"}" />。

其实也能够利用window对象来保存一些数据，像上面的例子，咱们能够在AJAX请求页直接包含这样的脚本块：<script>window.userData = { "name":"Tom"};</script>，当在AJAX请求回调函数中执行完$( "#MyDiv ").html(data)后，在window上就立刻有了这一变量。若是采用第一种方法，将不可避免eval(document.getElementById("UserData").innerHTML)。若是在window对象存放大量数据的话，这些数据不用时要及时手动清理它们，它们是要等浏览器刷新或重启后才会消失的，这就会增长内存开销。

 

6.16. 重视代码优化工做

代码最优化是每一个程序员应该努力达到的目标，也应该成为程序员永远的追求。写代码的时候，不该该急着把功能实现出来，要想一下如何写代码，代码的执行效率才是较好的。

举个例子：假设有定义getElementById的快捷方法functoin $(elemID){return document.getElementById(elemID)}，那么有人可能会写出这样的代码$("MyDiv").parentNode.removeChild($("MyDiv"))，其实这里执行了两次getElementById DOM查找，若是改为这样将更好：varmyDiv = $("MyDiv"); myDiv.parentNode.removeChild(myDiv)。还好getElementById的DOM查找算比较快，若是换成getElementsByTagName则更应该注重优化了。jQuery开发团队也有提醒你们要注意这方面的问题。

固然，代码优化技巧也是须要我的不断积累的。曾有朋友跟我说他写网站后台代码历来不用考虑优化的，由于他们网站用的是至强四核服务器，我以为这是很好笑的。

 

6.17. 能用面向对象方法进行接口定义和代码组织

这一能力对于每个程序员来讲都是很是重要的，这也是决定一个程序员水平高低的一个重要因素。可以把需求细化并抽象出不一样的类，而后有条理地编写代码，使代码结构清晰，可读性高，代码易于维护，不至于太过程化并且杂乱无章，这样才算是一个优秀的程序员。