js/javascript代码注释规范与示例
文件注释
文件注释位于文件的最前面,应包括文件的以下信息:概要说明及版本(必须)项目地址(开源组件必须)版权声明(必须)开源协议(开源组件必须)版本号(必须)修改时间(必须),以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代码注释规范与示例的更多相关文章
- java代码注释规范
java代码注释规范 代码注释是架起程序设计者与程序阅读者之间的通信桥梁,最大限度的提高团队开发合作效率.也是程序代码可维护性的重要环节之一.所以我们不是为写注释而写注释.下面说一下我们在诉求网二 ...
- PHPDocument 代码注释规范总结
PHPDocument 代码注释规范 1. 安装phpDocumentor(不推荐命令行安装)在http://manual.phpdoc.org/下载最新版本的PhpDoc放在web服务器目录下使得通 ...
- [转]java代码注释规范
代码注释是架起程序设计者与程序阅读者之间的通信桥梁,最大限度的提高团队开发合作效率.也是程序代码可维护性的重要环节之一.所以我们不是为写注释而写注释.下面说一下我们在诉求网二期开发中使用的代码注释规范 ...
- 代码注释规范-IDEA 配置 Java 类方法注释模板
1. 引言 团队开发时,业务模块分配的越清晰,代码注释管理越完善,越有利于后面维护,后面再管理也方便不少.另外也起着"文字砖"的作用,你懂的.注释不需要很详细,把代码块方法 ...
- 添加“返回顶部”小图标按钮的JS(JavaScript)代码详解
如何给自己的网站添加方便快捷的"返回顶部"小图标按钮呢?如下图: JS源代码: /** * JavaScript脚本实现回到页面顶部示例 * @param acceleration ...
- [C++]项目中的代码注释规范(整理)
原文:http://blog.csdn.net/pleasecallmewhy/article/details/8658795 1 源文件头部注释 列出:版权.作者.编写日期和描述. 每行不要超过80 ...
- java开发规范总结_代码注释规范
规范需要平时编码过程中注意,是一个慢慢养成的好习惯 1.基本规则 1.注释应该使代码更加清晰易懂 2.注释要简单明了,只要提供能够明确理解程序所必要的信息就可以了.如果注释太复杂说明程序需要修改调 ...
- 【js】JSDoc 注释规范
命令名描述 @param @argument 指定参数名和说明来描述一个函数参数@returns 描述函数的返回值@author 指示代码的作者@deprecated 指示一个函数已经废弃,而且在将来 ...
- 代码注释规范之Doxygen
1.Doxygen简介 Doxygen是一个程序的文档产生工具,可以将程序中的注释转换成说明文档或者说是API参考手册,从而减少程序员整理文档的时间.当然这里程序中的注释需要遵循一定的规则书写,才能让 ...
随机推荐
- 3.bootstrap练习笔记-媒体内容
bootstrap练习笔记-多媒体对象 1.在bootstrap中,如果想存放内容,一种解决的方式就是利用media这个class 首先要设置一个div.container作为一个总的容器来存放内容 ...
- 一次EF批量插入多表数据的性能优化经历
距离上次的博客已经有15个多月了,感慨有些事情还是需要坚持,一旦停下来很有可能就会停很久或者从此再也不会坚持.但我个人一直还坚持认为属于技术狂热份子,且喜欢精益求精的那种.最近遇到两个和数据迁移相关的 ...
- C#软件设计——小话设计模式原则之:单一职责原则SRP
前言:上篇C#软件设计——小话设计模式原则之:依赖倒置原则DIP简单介绍了下依赖倒置的由来以及使用,中间插了两篇WebApi的文章,这篇还是回归正题,继续来写写设计模式另一个重要的原则:单一职责原则. ...
- java-生成印章swing
案例1 package com; import java.awt.BorderLayout; import java.awt.Color; import java.awt.Font; import j ...
- 运行tomcat8w.exe未安装指定的服务
1.报错:指定的服务未安装. 2:解决方案有些写的不够详细,现在发表一遍详细操作手册 以上是解决方案备忘录
- mysql返回最后一列数据
获取MySQL的表中每个userid最后一条记录的方法,并且针对userid不唯一的情况,需要的朋友可以参考下 表结构 CREATE TABLE `t1` ( `userid` int(11) DEF ...
- 关于获取、设置css样式封装的函数入门版
<html> <head> <meta charset="UTF-8"> <title>CSS样式的获取和设置:简单版</ti ...
- MYSQL之基本操作
数据库操作 一.查看所有的数据库 show databases; 二.创建数据库 create database userinfo; 说明: 创建了一个名为userinfo的数据库 三.使用数据库 u ...
- <<< Oracle表创建、修改、删除基础操作
表是数据库存储数据的基本单元,它对应于现实世界中的对象(如部门和雇员等).表按列进行定义,存储若干行数据.表中应该至少有一列.在 Oracle 中,表一般指的是一个关系型数据表.也可以生成临时表和对象 ...
- Yocto开发笔记之《Tip-stdlib库函数strtod返回nan错误》(QQ交流群:519230208)
2015.04-imx_v2015.04_3.14.38_6ul_ga+g5d63276 (Jan 04 2016 - 18:07:08) FSL Community BSP : https://co ...