文件注释

文件注释位于文件的最前面,应包括文件的以下信息:概要说明及版本(必须)项目地址(开源组件必须)版权声明(必须)开源协议(开源组件必须)版本号(必须)修改时间(必须),以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

 */
/*!

 * kan.56.com - v1.1 (2013-03-08T15:30:32+0800)

 * Copyright 2005-2013 56.com

 */

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

/*!

 * 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

总是在多行注释的结束符前留一个空格(使星号对齐)。例如:

/*

                             

 */

不要把注释写在多行注释的开始符、结束符所在行。例如:

/* start

                             

end */
/*

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

 */

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

  • @module。声明模块,用法:

    /**
    
     * 模块说明
    
     * @module 模块名
    
     */

    例如:

    /**
    
     * Core模块提供最基础、最核心的接口
    
     * @module Core
    
     */

@class。声明类,用法:

/**

 * 类说明

 * @class 类名

 * @constructor

 */

@class必须搭配@constructor或@static使用,分别标记非静态类与静态类。

/**

 * 节点集合类

 * @class NodeList

 * @constructor

 * @param {ArrayLike<Element>} nodes 初始化节点

 */

@method。声明函数或类方法,用法:

/**

 * 方法说明

 * @method 方法名

 * @for 所属类名

 * @param {参数类型} 参数名 参数说明

 * @return {返回值类型} 返回值说明

 */

没有指定@for时,表示此函数为全局或模块顶层函数。当函数为静态函数时,必须添加@static;当函数有参数时,必须使用@param;当函数有返回值时,必须使用@return。

/**

 * 返回当前集合中指定位置的元素

 * @method

 * @for NodeList

 * @param {Number} [i=0] 位置下标。如果为负数,则从集合的最后一个元素开始倒数

 * @return {Element} 指定元素

 */

@param。声明函数参数,必须与@method搭配使用。

当参数出现以下情况时,使用对应的格式:

[参数名]

参数有默认值:

[参数名=默认值]

@property。声明类属性,用法:

/**

 * 属性说明

 * @property {属性类型} 属性名

 */

js/javascript代码注释规范与示例的更多相关文章

  1. java代码注释规范

    java代码注释规范   代码注释是架起程序设计者与程序阅读者之间的通信桥梁,最大限度的提高团队开发合作效率.也是程序代码可维护性的重要环节之一.所以我们不是为写注释而写注释.下面说一下我们在诉求网二 ...

  2. PHPDocument 代码注释规范总结

    PHPDocument 代码注释规范 1. 安装phpDocumentor(不推荐命令行安装)在http://manual.phpdoc.org/下载最新版本的PhpDoc放在web服务器目录下使得通 ...

  3. [转]java代码注释规范

    代码注释是架起程序设计者与程序阅读者之间的通信桥梁,最大限度的提高团队开发合作效率.也是程序代码可维护性的重要环节之一.所以我们不是为写注释而写注释.下面说一下我们在诉求网二期开发中使用的代码注释规范 ...

  4. 代码注释规范-IDEA 配置 Java 类方法注释模板

    1. 引言     团队开发时,业务模块分配的越清晰,代码注释管理越完善,越有利于后面维护,后面再管理也方便不少.另外也起着"文字砖"的作用,你懂的.注释不需要很详细,把代码块方法 ...

  5. 添加“返回顶部”小图标按钮的JS(JavaScript)代码详解

    如何给自己的网站添加方便快捷的"返回顶部"小图标按钮呢?如下图: JS源代码: /** * JavaScript脚本实现回到页面顶部示例 * @param acceleration ...

  6. [C++]项目中的代码注释规范(整理)

    原文:http://blog.csdn.net/pleasecallmewhy/article/details/8658795 1 源文件头部注释 列出:版权.作者.编写日期和描述. 每行不要超过80 ...

  7. java开发规范总结_代码注释规范

    规范需要平时编码过程中注意,是一个慢慢养成的好习惯 1.基本规则 1.注释应该使代码更加清晰易懂   2.注释要简单明了,只要提供能够明确理解程序所必要的信息就可以了.如果注释太复杂说明程序需要修改调 ...

  8. 【js】JSDoc 注释规范

    命令名描述 @param @argument 指定参数名和说明来描述一个函数参数@returns 描述函数的返回值@author 指示代码的作者@deprecated 指示一个函数已经废弃,而且在将来 ...

  9. 代码注释规范之Doxygen

    1.Doxygen简介 Doxygen是一个程序的文档产生工具,可以将程序中的注释转换成说明文档或者说是API参考手册,从而减少程序员整理文档的时间.当然这里程序中的注释需要遵循一定的规则书写,才能让 ...

随机推荐

  1. 洛谷P1119 灾后重建[Floyd]

    题目背景 B地区在地震过后,所有村庄都造成了一定的损毁,而这场地震却没对公路造成什么影响.但是在村庄重建好之前,所有与未重建完成的村庄的公路均无法通车.换句话说,只有连接着两个重建完成的村庄的公路才能 ...

  2. Linux提权(1)-基础版~

    利用Linux内核漏洞提权 VulnOS version 2是VulHub上的一个Linux提权练习,当打开虚拟机后,可以看到 获取到低权限SHELL后我们通常做下面几件事 1.检测操作系统的发行版本 ...

  3. block的哪些事 --- 学习笔记十

    //带有自动变量值的匿名函数 //block 与 C语言函数比只有两点不同,1.没有函数名. 2.带有"^". //类似于方法,如B中的值传给A中,在B中,一. 定义 : 二. 实 ...

  4. 快速掌握iOS API的一个小技巧

    快速掌握iOS API的一个小技巧 周银辉 iOS SDK和Developer Library中提供了各个类以及函数的帮助文档,这很棒,但要想了解整个库的大体结构(比如UIKit下有哪些类,他们的继承 ...

  5. 【笔记3】用pandas实现矩阵数据格式的推荐算法 (基于用户的协同)

    原书作者使用字典dict实现推荐算法,并且惊叹于18行代码实现了向量的余弦夹角公式. 我用pandas实现相同的公式只要3行. 特别说明:本篇笔记是针对矩阵数据,下篇笔记是针对条目数据. ''' 基于 ...

  6. 豪斯课堂K先生全套教程淘宝设计美工第一期+第四期教程(无水印)

    第一期课程包括 <配色如此简单> <配色的流程><对称之美>第二期课程包括 <字体的气质及组合><平衡及构图形式><信息的筛选与图片的 ...

  7. JS获取屏幕高度(转)

    IE中: document.body.clientWidth ==> BODY对象宽度 document.body.clientHeight ==> BODY对象高度 document.d ...

  8. JQurey

    jQuery 是一个 JavaScript 库.极大地简化了 JavaScript 编程,很容易学习. jQuery 是一个 JavaScript 函数库. jQuery 库包含以下特性: HTML ...

  9. php-fpm中启用慢日志配置(用于检测执行较慢的PHP脚本)

    虽然通过nginx accesslog可以记录用户访问某个接口或者网页所消耗的时间,但是不能清晰地追踪到具体哪个位置或者说函数慢,所以通过php-fpm慢日志,slowlog设置可以让我们很好的看见哪 ...

  10. WKWebView与JS交互,UIWebView+JavascriptCore和JS交互

    最近一直在做有关Swift和JavaScript交互的程序,所以有关UIWebView和WKWebView在使用上的差别在此总结下: UIWebView: (1)创建 var webView: UIW ...