《编写可维护的JavaScript》——JavaScript编码规范（四）

注释

单行注释

单行注释以两个斜线开始，以行尾结束

单行注释有三种使用方法：

• 独占一行的注释，用来解释下一行代码。这行注释前总是有一个空行，且缩进层级和下一行代码保持一致。
• 在行尾的注释。代码结束到注释之间至少有一个缩进。注释（包括之前的代码部分）不应当超过单行最大字符数限制。如果超过了，就将这条注释放置于当前代码行的上方。
• 被注释掉的大段代码（很多编辑器都可以批量注释掉多行代码）。

单行注释不应当以连续多行注释的形式出现，除非你注释掉一大段代码。只有当需要注释一段很长的文本时才使用多行注释

多行注释

多行注释可以包裹跨行文本。它以/*开始，以*/结束。多行注释不仅仅可以用来包裹跨行文本，这取决于你。

推荐的是java风格的多行注释。java风格的注释至少包含三行：第一行是/*，第二行是以*开始且和上一行的*保持左对齐，最后一行是*/。这种注释看起来像下面这样。

/*

* 另一段注释

* 这段注释包含两行文本

*/

通过在注释左侧注上星号，会让注释更清晰。有一些IDE（比如eclipse）会自动为你插入这些星号。星号后应有空格

多行注释总是出现在将要描述的代码段之前，注释和代码之间没有空行间隔。和单行注释一样，多行注释之前当有一个空行，且缩进层级和其要描述的代码保持一致。

使用注释

何时添加注释是程序员经常争论的一个话题。一种通行的指导原则是，当代码不够清晰时添加注释，而当代码很明了时不应当添加注释。

难于理解的代码通常都应当加注释。

可能被误认为错误的代码,需要添加注释

文档注释

从技术的角度来讲，文档注释并不是JavaScript的组成部分，但它们是一种普遍的实践。文档注释最流行的一种格式来源于JavaDoc文档格：多行注释以/**开始，接下来是描述信息，其中使用@符号来表示一个或多个属性。来看一段来自YUI的源码的例子。

/**
返回一个对象，这个对象包含被提供对象的所有属性。
后一个对象的属性会覆盖前一个对象的属性。
传入一个单独的对象，会创建一个它的浅拷贝（shallow copy）。
@method merge
@param {Object} 被合并的一个或多个对象
@return {Object} 一个新的合并后的对象
Y.merge = function(){

    //此处省略

    return result;
};

当使用文档注释时，你应当确保对如下内容添加注释。

• 所有的方法

应当对方法、期望的参数和可能的返回值添加注释描述

• 所有的构造函数

应当对自定义类型和期望的参数添加注释描述

• 所有包含文档化方法的对象

如果一个对象包含一个或多个附带文档注释的方法，那么这个对象也应当适当地针对文档生成工具添加文档注释。

<!--

作者：纤锐
出处：http://www.cnblogs.com/beginner2014
本文版权归作者和博客园共有，欢迎转载，但未经作者同意必须保留此段声明，且在文章页面明显位置给出原文连接。谢谢合作。

-->