文档章节

JavaScript编码规范

村长杨京京
 村长杨京京
发布于 2016/09/22 09:57
字数 4439
阅读 33
收藏 2

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. 能用面向对象方法进行接口定义和代码组织

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

© 著作权归作者所有

共有 人打赏支持
下一篇: Java编码规范
村长杨京京
粉丝 161
博文 876
码字总数 904789
作品 0
杭州
程序员
私信 提问
5 种 JavaScript 编码规范,你喜欢哪一个?

无论你是刚刚学习 JavaScript,还是正在准备大厂的前端面试,下面这 5 种 JavaScript 编码规范都值得你留意和参考。 什么是编码规范 编码规范就是指导如何编写和组织代码的一系列标准。通过阅...

达尔文
2017/11/13
3.2K
7
5 种JavaScript编码规范

什么是编码规范 编码规范就是指导如何编写和组织代码的一系列标准。通过阅读这些编码规范,你可以知道在各个公司里代码是如何编写的。 我们为什么需要编码规范 一个主要的原因是:每个人写代...

小旋风柴进
2018/06/16
0
0
前端开发规范手册(命名、HTML、CSS、JS、ES6、React)

简介 前端开发规范手册(命名、HTML、CSS、JS、ES6、React)完整链接,欢迎给出您的宝贵意见; GitHub源码地址,要是觉得文档还能凑合着看,欢迎 ~ 不以规矩,不能成方圆。 对于团队而言,统...

baldwin
02/19
0
0
浅谈 JavaScript 编程语言的编码规范

对于熟悉 C/C++ 或 Java 语言的工程师来说,JavaScript 显得灵活,简单易懂,对代码的格式的要求也相对松散。很容易学习,并运用到自己的代码中。也正因为这样,JavaScript 的编码规范也往往...

红薯
2010/08/10
332
3
JavaScript语言标识符和保留字

任何一种计算机语言都离不开标识符和保留字,下面我们将详细介绍JavaScript标识符和关键字。 标识符 标识符就是给变量、函数和对象等指定的名字。构成标识符的字母是有一定的规范,JavaScrip...

智捷课堂
2015/03/15
0
0

没有更多内容

加载失败,请刷新页面

加载更多

/sbin/ldconfig.real: /usr/local/lib/libcudnn.so.7 不是符号链接

平台:Ubuntu 18 LTS 问题描述 /sbin/ldconfig.real: /usr/local/lib/libcudnn.so.7 不是符号链接 解决办法:建立软连接 sudo ln -sf /usr/local/lib/libcudnn.so.7.1.3 /usr/local/lib/libc......

Pulsar-V
17分钟前
0
0
C++多线程之使用Mutex和Critical_Section

Mutex和Critical Section都是主要用于限制多线程(Multithread)对全局或共享的变量、对象或内存空间的访问。下面是其主要的异同点(不同的地方用绿色表示)。 Mutex Critical Section 性能和...

shzwork
31分钟前
0
0
AWS的自动部署工具codedeploy 部署前的准备工作

开始部署codedeploy: 1.先预置IAM用户: 创建一个IAM用户或使用一个与AWS相关联的用户; 复制以下的策略附加到IAM用户,向IAM用户赋予对codedeploy(及codedeploy所依赖的AWS服务和操作)的...

守护-创造
43分钟前
1
0
这可能是最详细的一线大厂Mysql面试题详解了

1、MySQL的复制原理以及流程 基本原理流程,3个线程以及之间的关联; 主:binlog线程——记录下所有改变了数据库数据的语句,放进master上的binlog中; 从:io线程——在使用start slave 之后...

Java干货分享
53分钟前
3
0
人的精力是什么?如何强化精力

人的精力是什么? 人的精力是什么? 精力指精神和体力。精神包括一个人的精神状态,兴奋度,做事情的投入度,专注度,持续时间等。 人的精力来源 人的精力有4种来源,身体的、情感的、思想的和...

莫库什勒
今天
5
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部