《编写可维护的JavaScript》——2.4　文档注释

本节书摘来自异步社区《编写可维护的JavaScript》一书中的第2章，第2.4节，作者： 【美】Nicholas C. Zakas 译者： 李晶 , 郭凯 , 张散集 更多章节内容可以访问云栖社区“异步社区”公众号查看。

2.4 文档注释

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

/**

返回一个对象，这个对象包含被提供对象的所有属性。

后一个对象的属性会覆盖前一个对象的属性。

传入一个单独的对象，会创建一个它的浅拷贝（shallow copy）。

如果需要深拷贝（deep copy），请使用clone()

@method merge

@param {Object} 被合并的一个或多个对象

@return {Object} 一个新的合并后的对象

Y.merge = function () {

 var args = arguments,

 i = 0,

 len = args.length,

 result = {};

 for (; i len; ++i) {

 Y.mix(result, args[i], true);

 return result;

YUI类库使用它自己的一个名叫YUIDoc的工具来根据这些注释生成文档。但是，它的格式几乎和JSDoc Toolkit（类库无关的）一模一样，在开源项目中JSDoc Toolkit的应用非常广泛，包括Google内部的很多开源项目。YUIDoc和JSDoc Toolkit之间的重要区别是，YUIDoc同时支持文档注释中的HTML和Markdown格式，而JSDoc Toolkit只支持HTML。

这里强烈推荐你使用文档生成工具来为你的JavaScript生成文档。JavaScript代码注释必须符合你所用的工具支持的格式，但很多文档生成工具都支持JavaDoc风格的文档注释。当使用文档注释时，你应当确保对如下内容添加注释。

所有的方法

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

所有的构造函数

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

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

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

当然，注释的详细格式和用法最终还是由你所选择的文档生成工具决定的。

编写可维护的JavaScript 软件生命周期中80%的成本都消耗在了维护上；而且几乎所有的维护者都不是代码的直接开发人。如何让自己写的代码让别人阅读起来更高效？当然是写代码的时候注入一些规范。那么在Javascript中有哪些编程风格值得我们去注重呢？这篇文章将总结《编写可维护的JavaScript》里面的观点。
《编写可维护的JavaScript》——2.4 文档注释 这里强烈推荐你使用文档生成工具来为你的JavaScript生成文档。JavaScript代码注释必须符合你所用的工具支持的格式，但很多文档生成工具都支持JavaDoc风格的文档注释。当使用文档注释时，你应当确保对如下内容添加注释。
《编写可维护的JavaScript》——导读 本书是为了帮助你完成你的工作。通常来讲，你可以任意使用本书中的程序和文档。你不需要在这之前联系我们获得使用许可，但若复制程序的关键部分除外。比如，你的程序使用了本书中的多段代码，这不需要获取我们的许可。
异步社区 异步社区(www.epubit.com)是人民邮电出版社旗下IT专业图书旗舰社区，也是国内领先的IT专业图书社区，致力于优质学习内容的出版和分享，实现了纸书电子书的同步上架，于2015年8月上线运营。公众号【异步图书】，每日赠送异步新书。