javascript 代码注释规范与示例

小咪咪 2022-02-21 08:19 279阅读 0赞

**文件注释**  
文件注释位于文件的最前面，应包括文件的以下信息：概要说明及版本（必须）项目地址（开源组件必须）版权声明（必须）开源协议（开源组件必须）版本号（必须）修改时间（必须），以ISO格式表示（可使用Sublime Text的InsertDate插件插入）文件注释必须全部以英文字符表示，并存在于文件的开发版本与生产版本中。例如：

/*! * jRaiser 2 Javascript Library * waterfall - v1.0.0 (2013-03-15T14:55:51+0800) * http://jraiser.org/ | Released under MIT license */

如果文件内包含了一些开源组件，则必须在文件注释中进行说明。例如：

/*! * jRaiser 2 Javascript Library * sizzle - v1.9.1 (2013-03-15T10:07:24+0800) * http://jraiser.org/ | Released under MIT license * * Include sizzle (http://sizzlejs.com/) */

**普通注释**  
普通注释是为了帮助开发者和阅读者更好地理解程序，不会出现在API文档中。其中，单行注释以“//”开头；多行注释以“/*”开头，以“*/”结束。普通注释的使用需遵循以下规定。

*  总是在单行注释符后留一个空格。例如：

// this is comment

*  总是在多行注释的结束符前留一个空格（使星号对齐），不要把注释写在多行注释的开始符、结束符所在行。例如：

/* here is line 1 here is line 2 */

*  不要编写无意义的注释。例如：

// 初始化value变量为0
    var value = 0;

*  如果某段代码有功能未实现，或者有待完善，必须添加“TODO”标记，“TODO”前后应留一个空格。例如：

// TODO 未处理IE6-8的兼容性
    function setOpacity(node, val) { 
        node.style.opacity = val;
    }

**文档注释**  
文档注释将会以预定格式出现在API文档中。它以“/\*\*”开头，以“*/”结束，其间的每一行均以“*”开头（均与开始符的第一个“*”对齐），且注释内容与“*”间留一个空格。例如：

/** * comment */

文档注释必须包含一个或多个注释标签。