JavaScript 注释规范

2019-1-8 00:59| 作者: admin| 查看: 5666| 评论: 1|来自: 蚂蚁部落

HTML与CSS都有注释,但是这两者的注释比JavaScript注释要简单的多。

主要原因是因为HTML和CSS代码相对比较简单,它们都算不上真正的编程语言。

面对结构庞大且繁杂的JavaScript代码,较为科学的注释更有利于项目的团队开发,后期维护也会便利。

下面分布介绍一下注释的总体原则、注释的基本语法和对常见语法结构的注释规则推荐。

一.注释总体原则:

能不注释,尽量不对代码添加注释,以减少体积。

如果必须要注释,则注释必须详尽,格式科学,提高代码的可读性。

也就是说注释并不是用来美化代码的,而是为了便于自己活着其他程序员的阅读便利性。

它是一种负担,但是为了团队开发等目的又是必要的。

二.单行注释:

两个斜杠//可以创建一个单行注释,斜杠后面要增加一个空格,紧接着是注释内容。

注释的缩进需要与所注释的代码一致,且要位于被注释代码的上面。

代码演示如下:

[JavaScript] 纯文本查看 复制代码
// 蚂蚁部落教程测试函数
function func() {
  // 用来存储定时器函数标识
  let flag = null;
}

三.多行注释:

/**/可以创建多行注释,也就是以"/*"开始,"*/"结束,中间是注释内容。

既然是多行注释,自然被注释的内容是可以换行的。

尽量使用单行注释替代多行注释,如果注释函数,推荐使用多行注释。

四.函数的注释:

函数是使用最为频繁的语法结构,相对较为复杂,所以良好的注释对于理解函数的功能非常有必要。

注释格式如下:

[JavaScript] 纯文本查看 复制代码
/*方法说明
 *@method 方法名
 *@for 所属类名
 *@param{参数类型}参数名 参数说明
 *@return {返回值类型} 返回值说明
*/

可以看到在注释的开始于结尾分别是/*与*/,具体的注释内容前面也带有一个星号,看起来更加整齐。

看一段简单的注释代码实例:

[JavaScript] 纯文本查看 复制代码
/*函数说明
 * @param {string} p1 参数1的说明
 * @param {string} p2 参数2的说明,比较长
 *     那就换行了.
 * @param {number=} p3 参数3的说明(可选)
 * @return {Object} 返回值描述
 */
 function foo(p1, p2, p3) {
  var p3 = p3 || 10;
  return {
    p1: p1,
    p2: p2,
    p3: p3
  };
}

五.模块注释:

模块注释格式如下:

[JavaScript] 纯文本查看 复制代码
/* 模块说明
* @module 模块名
*/

六.class类注释:

ES2015新增类的概念,具体参阅JavaScript class 类一章节。

类的注释格式如下:

[JavaScript] 纯文本查看 复制代码
/* 类说明
 * @class 类名
 * @constructor
 */

由于类分为静态类与非静态类,所以@class需要与@constructor或者@static配合使用。

七.注释内容:

知道为什么需要注释,那么也就知道注释应该怎么写。

注释的目的是告诉阅读者不宜察觉或者不易获取到的信息,而不是一目了然的东西。

下面的注释就相当于废话,根本就不需要:

[JavaScript] 纯文本查看 复制代码
// 声明一个变量timer
let timer=null;

只要不是JavaScript盲,都能知道上面是声明一个变量,根本用不着注释。

应该强调tmer这个变量将来要发挥的作用,代码修改如下:

[JavaScript] 纯文本查看 复制代码
// 声明变量用来存储定时器函数的标识
let timer=null;

八.待办内容:

可能有些地方的代码待编写或者有些功能待实现。

那么可以使用// TODO标识出来,格式如下:

[JavaScript] 纯文本查看 复制代码
// TODO: 标注待实现的功能。

九.有bug待处理:

如果代码有些地方需要优化,甚至代码中存在错误去修正。

那么可以使用// FIXME标注出来,格式如下:

[JavaScript] 纯文本查看 复制代码
// FIXME: 标注出现的问题。

上面介绍的仅是常见的注释,JavaScript语法结构很多,感兴趣的朋友可以自行总结。 

  

1

鲜花

握手

雷人

路过

鸡蛋

刚表态过的朋友 (1 人)

发表评论

最新评论

引用 fghjkl098762134 2019-5-12 17:12
Sfdghk.k;

查看全部评论(1)

返回顶部