JavaScript 代码开发规范与最佳实践指南

在过往的开发经历中，我曾与不遵循编码规范的同事合作，这种体验并不理想。撰写本文旨在分享个人经验，为未来的团队协作提供借鉴，同时也恳请业界前辈指正其中可能存在的疏漏。以下列出的各项规范要求，主要针对常见的编码陋习提出，部分行业通用规范此处不再赘述。

1、确保代码压缩后无错误

针对大型JavaScript项目，产品发布时通常会对所有JS文件进行压缩处理，例如使用Google Closure Compiler Service（新版jQuery已采用此工具）。压缩过程会移除注释、空格、换行，并将长变量名替换为短无意义名称，以加快下载速度、减少流量消耗并提供一定的代码保护。为确保压缩成功，语句必须以分号结尾，大括号需严格闭合，具体需遵循压缩工具的要求。若初期未遵循标准，后续排查压缩错误将耗费大量时间。

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

完善的开发工具（如Aptana Studio）通常具备“自动格式化”功能，可统一换行、缩进和空格等排版细节。开发者可自定义格式标准（如左大括号是否另起一行）。此举旨在方便团队成员使用IDE将代码格式化为其习惯的风格进行阅读。当编写通用方法供其他模块使用时，清晰的代码格式有助于深入理解方法调用和实现细节，这是简单API文档无法替代的。

3、使用标准的文档注释

这是最基本的要求，有利于在调用处查看参数提示，并可利用配套工具（如jsdoc-toolkit）生成HTML等格式的文档供团队阅读。若开发开放平台（如Facebook应用），文档面向所有开发者。完整的注释不仅便于团队成员理解参数和实现细节，也利于长期维护，即使项目庞大且时隔久远，也能清晰回顾代码逻辑。

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

规范且具意义的变量名能提升代码可读性。在大项目中，代码量巨大，规范命名不仅便于他人理解，也方便自己日后回顾，特别是在系统升级或新增功能时，清晰命名能简化修改工作。若日后连自己编写的代码都无法理解，那将是极大的失误。

此外，变量命名应尽量遵循标准，例如使用`var self = this`比`var me = this`更佳，因为`self`在Python中对应`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`获取参数，因为若方法包含较多脚本，使用`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'); }

<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`。此外，若按钮名称由中文改为英文，也会出现问题。因此，这种做法存在诸多缺陷。

10、一个函数应返回统一的数据类型

JavaScript是弱类型语言，编写函数时有些人对返回类型处理随意。我认为应像强类型语言那样返回。看以下两个例子：

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数据，以待页面下载后将来使用，如：`<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对象存放大量数据，不用时应及时手动清理，否则需等待浏览器刷新或重启才会消失，从而增加内存开销。

16、永远不要忽略代码优化工作

代码最优化是每位程序员应努力达到的目标，也应成为永远的追求。编写代码时，不应急于实现功能，而应思考如何编写代码，以提高执行效率。

举例：假设有定义getElementById的快捷方法`functoin $(elemID){return document.getElementById(elemID)}`，有人可能写出这样的代码`$("MyDiv").parentNode.removeChild($("MyDiv"))`，这里执行了两次getElementById DOM查找。若改为`var myDiv = $("MyDiv"); myDiv.parentNode.removeChild(myDiv)`则更佳。还好getElementById的DOM查找较快，若换成getElementsByTagName，则更应注重优化。jQuery开发团队也提醒大家注意此问题。

当然，代码优化技巧需个人不断积累。曾有朋友称写网站后台代码从不考虑优化，因其网站使用至强四核服务器，我认为这很可笑。

17、会分析策划文档，能用面向对象方法进行接口定义和代码组织

这一能力对每位程序员都至关重要，也是决定程序员水平高低的重要因素。能够将需求细化并抽象出不同类，然后有条理地编写代码，使代码结构清晰、可读性高、易于维护，不至于太过程化且杂乱无章，这才算是一名优秀的程序员。 作者：WebFlash 出处：http://webflash.cnblogs.com