Javascript编码规范.docx

Javascript编码规范.docx

《Javascript编码规范.docx》由会员分享，可在线阅读，更多相关《Javascript编码规范.docx（9页珍藏版）》请在冰豆网上搜索。

Javascript编码规范

Javascript编码规范

当前版本

V1.0

发布日期

2012-09-12

文档变更记录

版本

修订人

修订日期

修订内容

审核人

批准人

V1.0

刘霏

2011-7-29

初建文档

EPG

仝永波

说明：

1.修订日期格式统一为：

yyyy-mm-dd

2.修订内容中简要记录每次修订涉及的章节及内容。

目录

1.目的4

2.适用范围5

3.版权声明5

4.参考资料5

5.概述5

6.规范要求6

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

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

6.3.使用标准的文档注释7

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

6.5.不使用生偏语法8

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

6.7.明确定义函数固定数量的参数9

6.8.不必热衷动态事件绑定9

6.9.降低代码与XHTML的耦合性10

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

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

6.12.不在文件中留下未来确定不再使用的代码片段12

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

6.14.调用合适的方法13

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

6.16.重视代码优化工作14

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

1.目的

本规范的目的是使本组织能以标准的、规范的方式设计和编码。

通过建立编码规范，以使每个开发人员养成良好的编码风格和习惯；并以此形成开发小组编码约定，提高程序的可靠性、可读性、可修改性、可维护性和一致性等，增进团队间的交流，并保证软件产品的质量。

2.适用范围

本规范适用于普信恒业科技发展（北京）有限公司技术部所有软件开发人员，在整个软件开发过程中必须遵循此规范。

3.版权声明

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

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

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

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

4.参考资料

✧《SunJava语言编码规范》（JavaCodeConventions）

5.概述

这是一套适用于JavaScript程序的编码规范。

它基于Sun的Java程序编码规范。

但进行了大幅度的修改,因为JavaScript不是Java。

对于代码，首要要求是它必须正确，能够按照设计预定功能去运行；第二是要求代码必须清晰易懂，使自己和其他的程序员能够很容易地理解代码所执行的功能等。

然而，在实际开发中，每个程序员所写的代码却经常自成一套，很少统一，导致理解困难，影响团队的开发效率及系统的质量等。

因此，一份完整并被严格执行的开发规范是非常必须的，特别是对软件公司的开发团队而言。

最根本的原则：

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

运用常识。

当找不到任何规则或指导方针，当规则明显不能适用，当所有的方法都失效的时侯，运用常识并核实这些基本原则。

这条规则比其它所有规则都重要。

常识是必不可少。

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

6.规范要求

1.

2.

3.

4.

5.

6.

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

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

要想代码能正确通过压缩，一般要求语句都要以分号正常结束，大括号也要严格结束等，具体还要看压缩工具的要求。

所以如果一开始没有按标准来做，等压缩出错后再回去找错误那是浪费时间。

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

一般较为完善的开发工具（比如AptanaStudio）都有代码“自动格式”化功能，这一功能帮助实现统一换行、缩进、空格等代码编排，你可以设置自己喜欢的格式标准，比如左大括号{是否另起一行。

达到这个要求的目的在于方便你的开发团队成员拿你代码的一个副本用IDE自动格式化成他喜欢或熟悉的风格进行阅读。

你同事需要阅读你的代码，可能是因为你写的是通用方法，他在其它模块开发过程中也要使用到，阅读你的代码能最深入了解方法调用和实现的细节，这是简单API文档不能达到的效果。

6.3.使用标准的文档注释

这一要求算是最基本的，这有利于在方法调用处看到方法的具体传参提示，也可以利用配套文档工具生成html或其它格式的开发文档供其他团队成员阅读，你可以尝试使用jsdoc-toolkit。

如果你自动生成的API是出自一个开放平台，就像应用，那么你的文档是给天下所有开发者看的。

另外编写完整注释，也更方便团队成员阅读你的代码，通过你的参数描述，团队成员可以很容易知道你编写的方法传参与实现细节。

当然也方便日后代码维护，这样即使再大的项目，过了很长时间后，回去改点东西也就不至于自己都忘记了当时自己写的代码是怎么一回事了。

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

使用规范有意义的变量名可以提高代码的可读性，作为大项目开发成员，自己写的代码不仅仅要让别人容易看懂。

开发大项目，其实每个人写的代码量可能都比较大，规范命名，日后自己看回自己的代码也显的清晰易懂，比如日后系统升级或新增功能，修改起代码来也轻松多了。

如果到头发现自己当初写的代码现在看不太懂了，那还真是天大的笑话了。

当然，使用有意义的变量名也尽量使用标准的命名，比如像这里：

varme=this也许没有varself=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）{varp=a;}（'a'）应该改为：

（function（a）{varp=a;}）（'a'），其实function前面的+号与包含function的（）括号作用是一样的，都是起运算优先作用，后者是常见且容易看明白的防止变量污染的做法，比如好些流行JavaScript框架就是采用后面这种方式。

再说个降低代码可读性的例子，如：

functiongetPostionTxt（type）{returntype==2?

"野外":

（type==3?

"商城":

（type==4?

"副本":

null））;}应该改成：

functiongetPostionTxt（type）{vartypeData={"2":

"野外","3":

"商城","4":

"副本"};if（typeData[type]）returntypeData[type];elsereturnnull;}。

如果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'）; 

} 

;" onclick="myBtnClick（this）">确定

;" onclick="myBtnClick（this）">取消 

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

，

那么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）{returndocument.getElementById（elemID）}那么就不应该在Mail.js中再次出现这一功能函数的重复定义，对于一些复杂的方法更应该如此。

6.14.调用合适的方法

当有几个方法都可以实现同类功能的时候，我们还是要根据场景选择使用最合适的方法。

下面拿jQuery框架的两个AJAX方法来说明。

如果确定服务器返回的数据是JSON应该直接使用$.getJSON，而不是使用$.get得到数据再用eval函数转成JSON对象。

如果因为本次请求要传输大量的数据而不得以使用$.post也应该采用指定返回数据类型（设置dataType参数）的做法。

如果使用$.getJSON，在代码中我们一眼能看出本次请求服务器返回的是JSON。

温馨提示：

jQuery1.4后，如果服务器有设置数据输出的ContentType，比如ASP.NETC#设置Response.ContentType="application/json"，那么$.get将与$.getJSON的使用没有什么区别。

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

曾发现有人利用DIV来保存JSON数据，以待页面下载后将来使用，像这样：

{"name":

"Tom"}