javascript注释规范
注释在代码编写过程中的重要性,写代码超过半年的就能深深的体会到。没有注释的代码都不是好代码。为了别人学习,同时为了自己以后对代码进行‘升级’,看看js/javascript代码注释规范与示例。来自:http://www.56.com/style/-doc-/v1/tpl/js_dev_spec/spec-comment.html
文件注释
文件注释位于文件的最前面,应包括文件的以下信息:概要说明及版本(必须)项目地址(开源组件必须)版权声明(必须)开源协议(开源组件必须)版本号(必须)修改时间(必须),以ISO格式表示(可使用Sublime Text的InsertDate插件插入)文件注释必须全部以英文字符表示,并存在于文件的开发版本与生产版本中。例如:
1
2
3
4
5
|
/*! * * * */ |
1
2
3
4
|
/*! * * */ |
如果文件内包含了一些开源组件,则必须在文件注释中进行说明。例如:
1
2
3
4
5
6
7
|
/*! * * * * * */ |
普通注释
普通注释是为了帮助开发者和阅读者更好地理解程序,不会出现在API文档中。其中,单行注释以“//”开头;多行注释以“/*”开头,以“*/”结束。普通注释的使用需遵循以下规定。
总是在单行注释符后留一个空格。例如:
1
|
// |
总是在多行注释的结束符前留一个空格(使星号对齐)。例如:
1
2
3
|
/* */ |
不要把注释写在多行注释的开始符、结束符所在行。例如:
1
2
3
|
/* end |
1
2
3
4
|
/* here here */ |
不要编写无意义的注释。例如:
1
2
|
// var value |
如果某段代码有功能未实现,或者有待完善,必须添加“TODO”标记,“TODO”前后应留一个空格。例如:
1
2
3
4
|
// function setOpacity(node, node.style.opacity } |
文档注释
文档注释将会以预定格式出现在API文档中。它以“/**”开头,以“*/”结束,其间的每一行均以“*”开头(均与开始符的第一个“*”对齐),且注释内容与“*”间留一个空格。例如:
1
2
3
|
/** * */ |
文档注释必须包含一个或多个注释标签。
@module。声明模块,用法:
1
2
3
4
|
/** * * */ |
例如:
1
2
3
4
|
/** * * */ |
@class。声明类,用法:
1
2
3
4
5
|
/** * * * */ |
@class必须搭配@constructor或@static使用,分别标记非静态类与静态类。
1
2
3
4
5
6
|
/** * * * * */ |
@method。声明函数或类方法,用法:
1
2
3
4
5
6
7
|
/** * * * * * */ |
没有指定@for时,表示此函数为全局或模块顶层函数。当函数为静态函数时,必须添加@static;当函数有参数时,必须使用@param;当函数有返回值时,必须使用@return。
1
2
3
4
5
6
7
|
/** * * * * * */ |
@param。声明函数参数,必须与@method搭配使用。
当参数出现以下情况时,使用对应的格式:
1
|
[参数名] |
参数有默认值:
1
|
[参数名=默认值] |
@property。声明类属性,用法:
1
2
3
4
|
/** * * */ |
javascript注释规范的更多相关文章
- JavaScript 注释规范
JavaScript 注释规范 总原则 As short as possible(如无必要,勿增注释).尽量提高代码本身的清晰性.可读性. As long as necessary(如有必要,尽量详尽 ...
- sublime注释插件与javascript注释规范
前言 代码中注释是不可少的,即使是自己写的代码,过了一段时间之后再重看,如果没有注释记录的话,可能会想不到当初是这样实现的,尤其是在业务逻辑比较复杂的项目,注释变得尤为重要.怎么优雅的写有用的注释呢? ...
- Sublime Text3 插件:DocBlockr与javascript注释规范
原:http://www.ithao123.cn/content-719950.html 1.引子 在写代码的时候,尤其是写脚本,最需要注释了.目前脚本.样式的注释格式都有一个已经成文的约定规范(这些 ...
- 【JavaScript 开发规范】
Javascript 最佳实践http://sofish.de/1171http://sofish.de/1181 总是使用 ‘var’ √ 特性检测而非浏览器检测 √ 使用方括号记法 √ 使用&qu ...
- JavaScript语法规范
推荐的JavaScript编码规范 阅读 247 评论 0 喜欢 0 作为前端开发人员,我相信每一个人都或多或少的用到原生的JavaScript,也正是因为用的人多,导致编码风格也是多种多样的,而不规 ...
- JavaScript编码规范指南
前言 本文摘自Google JavaScript编码规范指南,截取了其中比较容易理解与遵循的点作为团队的JavaScript编码规范. JavaScript 语言规范 变量 声明变量必须加上 var ...
- JavaScript编码规范[百度]
JavaScript编码规范 1 前言 2 代码风格 2.1 文件 2.2 结构 2.2.1 缩进 2.2.2 空格 2.2.3 换行 2.2.4 语句 2.3 命名 ...
- JavaScript 代码规范
所有的 JavaScript 项目适用同一种规范. JavaScript 代码规范 代码规范通常包括以下几个方面: 变量和函数的命名规则 空格,缩进,注释的使用规则. 其他常用规范-- 规范的代码可以 ...
- JavaScript 编码规范(中文/Airbnb公司版)
Airbnb 是一家位于美国旧金山的公司,本文是其内部的 JavaScript编码规范,写得比较全面,在 Github 上有 16,686 + Star,3,080 + fork,前端开发人员可参考. ...
随机推荐
- vertical-align属性详解
vertical-align属性详解:http://www.cnblogs.com/wcp-spring/archive/2013/03/04/2942456.html 关于vertical-alig ...
- js的特殊运算符
1)三元条件运算符: c是一个布尔值,当c为true的时候,取冒号左边a的值,否取冒号右边的b的值: 2)逗号运算符: 值从左到右依次计算,取最右边的,例如例子里的val,会取最右边的值3: 特殊运算 ...
- Hibernate 框架基本知识
QTP:Quick Test Pressional 1,Hibernate是一个优秀的java持久化层解决方案,是当今主流的对象-关系映射(ORM,ObjectRelationalMapping)工具 ...
- 逆向思维 UVA 11853
题目大意:紫书175 思路:看书...2333 关键点就是利用已知条件来逆向思考是否能走通,而不是傻傻的从某个点开始出发啊啥的.
- ng-Directive
伪代码: var myModule = angular.module(...); myModule.directive('namespaceDirectiveName', function facto ...
- 关于function
场景:让用户输入一个数字,程序由1+2....一直累加到用户输入的数字为止 #!/bin/bashPATH=$PATH:~/scriptexport PATH #chech whether the i ...
- hive-1.2.1安装步骤
一.Hive安装和配置 1.先决条件 已经安装好hadoop-2.4.1,hbase-1.0.0. 2.下载Hive安装包 当前Hive可到apache官网下载,选择的是hive-1.2.1.运行: ...
- sqlserver2012评估期已过问题处理
于之前安装sqlserver2012忘记输入序列号,现在出现评估期已过的问题,网上忙活半天,才解决,发现网上叙述都很凌乱,而且只有大意,新手很难操作,所以把我操作的过程分享给大家 步骤阅读 百度经 ...
- dom4j操作xml文档
java Dom4j解析XML文件 标签(空格分隔):java进阶 xml文档: <?xml version="1.0" encoding="UTF-8" ...
- 如何阅读一本书([美] 莫提默·J. 艾德勒 / 查尔斯·范多伦 )
进入豆瓣读书 前言 2017年1月2日跟着熊猫书院开始了为期十月的阅读计划. 熊猫书院是一个微信公众号,但仅对熊猫书院学员开放.它是一个很好的读书产品,从入学申请.入学报到.班长 ...