JavaScript development specification requirements (with pictures and texts)_javascript skills

本人在开发工作中就曾与不按规范来开发的同事合作过，与他合作就不能用“愉快”来形容了。现在本人撰写此文的目的除了与大家分享一点点经验外，更多的是希望对未来的合作伙伴能够起到一定的借鉴作用。当然，如果我说的有不科学的地方还希望各路前辈多多指教。下面分条目列出各种规范要求，这些要求都是针对同事编码毛病提出来的，好些行业约定的其它规范可能不会再提及。

1、保证代码压缩后不出错

对于大型的JavaScript项目，一般会在产品发布时对项目包含的所有JavaScript文件进行压缩处理，比如可以利用Google Closure Compiler Service对代码进行压缩，新版jQuery已改用这一工具对代码进行压缩，这一般会去掉开发时写的注释，除去所有空格和换行，甚至可以把原来较长的变量名替换成短且无意义的变量名，这样做的目的是加快文件的下载速度，同时也减小网站访问带来的额外数据流量，另外在代码保护上也起到了一点点作用，至少压缩后的代码即使被还原还是没那么容易一下读懂的。要想代码能正确通过压缩，一般要求语句都要以分号正常结束，大括号也要严格结束等，具体还要看压缩工具的要求。所以如果一开始没有按标准来做，等压缩出错后再回去找错误那是浪费时间。

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

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

3、使用标准的文档注释

这一要求算是最基本的，这有利于在方法调用处看到方法的具体传参提示，也可以利用配套文档工具生成html或其它格式的开发文档供其他团队成员阅读，你可以尝试使用jsdoc-toolkit。如果你自动生成的API是出自一个开放平台，就像facebook.com应用，那么你的文档是给天下所有开发者看的。另外编写完整注释，也更方便团队成员阅读你的代码，通过你的参数描述，团队成员可以很容易知道你编写的方法传参与实现细节。当然也方便日后代码维护，这样即使再大的项目，过了很长时间后，回去改点东西也就不至于自己都忘记了当时自己写的代码是怎么一回事了。

4、使用规范有意义的变量名

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

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

var li = document.getElementsByTagName('li')
var lis = document.getElementsByTagName('li')

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框架就是采用后面这种方式。

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

6、不在语句非赋值地方出生中文

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

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

7、明确定义函数固定数量的参数

固定数量参数的函数内部不使用arguments去获取参数，因为这样，你定义的方法如果包含较多的脚本，就不能一眼看到这个方法接受些什么参数以及参数的个数是多少。比如像下面：
var $ = function(){return document.getElementById(arguments[0]);}应该改成：var $ = function(elemID){return document.getElementById(elemID);}

8、不必热衷动态事件绑定

虽然知道事件可以动态绑定，比如使用addEventListener或者使用jQuery的bind方法，也知道采用动态事件绑定可以让XHTML更干净，但是一般情况下我还是建议直接把事件写在DOM节点上，我认为这样可以使代码变得更容易维护，因为这样做，我们在查看源代码的时候就可以容易地知道什么Element绑定了什么方法，简单说这样更容易知道一个按钮或链接点击时调了什么方法脚本。

9、降低代码与XHTML的耦合性

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

function myBtnClick(obj)
{
　if (/确定/.test(obj.innerHTML))
　　alert('OK');
　else if (/取消/.test(obj.innerHTML))
　　alert('Cancel');
　else
　　alert('Other');
}

确定取消

上面例子其实在一个函数内处理了两件事情，应该分成两个函数，像上面的写法，如果把链接换成按钮，比如改成这样：，那么myBtnClick函数内部的obj.innerHTML就出问题了，因为此时应该obj.value才对，另外如果把按钮名称由中文改为英文也会出问题，所以这种做法问题太多了。

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进行判断。

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

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

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

当代码调整或重构后，之前编写的不再使用的代码应该及时删除，如果认为这些代码还有一定利用价值可以把它们剪切到临时文件中。留在项目中不仅增加了文件体积，这对团队其它成员甚至自己都起到一定干扰作用，怕将来自己看回代码都搞不懂这方法是干什么的，是否有使用过。当然可以用文档注释标签@deprecated把这个方法标识为不推荐的。

13、不重复定义其他团队成员已经实现的方法

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

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

14、调用合适的方法

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

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

15、使用合适的控件存储合适的数据

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

{ "name":"Tom"}

, obviously this DIV is not used for interface display. If you must do this to achieve the effect of using HTML files for data caching, it is more reasonable to at least use a hidden field to store the data, such as changing it to: .

In fact, you can also use the window object to save some data. Like the example above, we can directly include such a script block in the AJAX request page: <script>window.userData = { "name":"Tom"}; </script>, after $( "#MyDiv ").html(data) is executed in the AJAX request callback function, this variable will be available on the window immediately. If you adopt the first method, eval(document.getElementById("UserData").innerHTML) will be inevitable. If a large amount of data is stored in the window object, the data must be cleaned manually in time when not in use. They will not disappear until the browser is refreshed or restarted, which will increase memory overhead.

16. Never ignore code optimization work

Code optimization is a goal that every programmer should strive to achieve, and it should also be a programmer’s eternal pursuit. When writing code, you should not rush to implement the function. Think about how to write the code so that the execution efficiency of the code is better.

For example: Suppose there is a shortcut method functoin $(elemID){return document.getElementById(elemID)} that defines getElementById, then someone may write such code $("MyDiv").parentNode.removeChild($ ("MyDiv")), in fact, two getElementById DOM searches are performed here. It would be better if it was changed to this: var myDiv = $("MyDiv"); myDiv.parentNode.removeChild(myDiv). Fortunately, the DOM search of getElementById is relatively fast. If you change it to getElementsByTagName, you should pay more attention to optimization. The jQuery development team has also reminded everyone to pay attention to this issue.

Of course, code optimization skills also require continuous accumulation by individuals. A friend once told me that he never had to consider optimization when writing website back-end code because their website used a Xeon quad-core server. I thought this was ridiculous.

17. Be able to analyze planning documents and use object-oriented methods to define interfaces and organize code.

This ability is very important for every programmer, and it is also an important factor that determines the level of a programmer. A good programmer is someone who can refine requirements and abstract them into different classes, and then write code in an orderly manner so that the code structure is clear, highly readable, easy to maintain, and not too procedural and messy.

Author: WebFlash