你不知道的JavaScript注释

最新推荐文章于 2023-10-11 17:01:58 发布

今晚打小强

最新推荐文章于 2023-10-11 17:01:58 发布

阅读量371

点赞数

分类专栏：前端相关

本文链接：https://blog.csdn.net/yftk765768540/article/details/103533044

版权

前端相关专栏收录该内容

5 篇文章 0 订阅

订阅专栏

一、JavaScript注释

注释用来在源码中增加提示、笔记、建议、警告等信息，可以帮助阅读和理解源码。在调试时，可以用来将一段代码屏蔽掉，防止其运行。

JavaScript的注释分为单行注释 // 和多行注释 /* */ 两种。

在单行注释中，在 // 后的文本都会视为注释，用法如下。

function comment() {
  // 这是单行注释
  console.log("Hello world!"); // 这是单行注释
}
comment();

在多行注释中，使用 /* 和 */ 包裹的文本就会视为注释，用法如下：

function comment() {
  /* 单行注释 */
  /* 多行注释，
     直到终止符号才结束 */
  console.log("Hello" + /* 引入x的值 */ + " world!");
}
comment();

二、JavaScript注释使用建议

注释的规范使用是可以方便他人阅读你的代码，同时，当你以后再次看的时候，也能很快回忆起。**写注释的时候，请记得写正确的注释，错误或有歧义的注释不如不写注释。**以下是本人对注释使用的一些心得，各位读者有别的想法可以提出，大家共同讨论。

2.1 单行注释的使用

变量、常量定义

变量、常量定义时，如果做不到见名知义，就请加上名称的描述。个人习惯加在声明语句的上方。

// 是否处于加载中
var isLoading = false;

// 手机号
const PHONE_NUMBER = '188xxxxxxxx';

代码块、流程控制代码

当出现连续代码块处理某一事件或出现包括但不限于 for in 、 each 、 while 、 do while 等这些有循环作用的代码时，就使用单行注释。

var sum = 0;

// 求sum对3取余的结果
var result;

// 求10以内大于5的数字之和
for (var i = 0; i < 10; i++) {
	// 当i大于5时累加
	if (i > 5) {
		sum += i;
	}
}

// sum对3取余
result = sum % 3;

添加TODO时

当代码中有部分业务未完成，或是有bug待解决，可以使用单行注释加TODO来标记。

function foo() {
	// TODO：未完成
}

2.2 多行注释的使用

在function和class上面添加方法和类的说明。（class是es6里的语法）

/**
 * 学生类
 */
class Student {
	/**
	 * 构造方法
	 */
	constructor() {}
}

三、关于注释的思考

上面三项是关于单行注释的使用建议，为何建议使用单行注释呢？

最开始学习编程的时候，是因为别人制定的规范，写习惯后觉得特别的方便，也具有一定区分性。后来是在阅读《JavaScript语言精粹》一书中关于的注释的部分，才理解到在代码逻辑区域写多行注释可能会产生问题。

假如在代码中出现一段这样的字符串 '*/ 这是一段文本'，你在注释的时候的，不小心在这段前后加上了一段多行注释，那这个代码就会出现语法错误了。这个例子如果不好理解，可以放进IDE里看一下，会更清楚一些。

// 单行注释的情况
// '*/ alert("1")/*'

/* 多行注释的情况 */
/*'*/ alert("1")' */

说到这里，会不会想到vscode这些IDE的快捷注释，是不是js都是用单行来注释的呢！

思考到这里还可以继续深入

按照刚才思路继续下去，如果是字符串中带有*/或/*，加上多行注释后会有注释之外的语句还可以运行。恰好这部分可以运行的语句是别人写了一段注入脚本呢？

直接上代码看一下：

/*
'*/ alert("1")/*'
*/

这段代码里，alert(“1”)直接就会弹出来，毕竟注释直接把引号给隐藏了。那我们伪装一下：

/*
'*%2F alert("1")%2F*'
*/

这样就是一句正常的注释了，解释器也不会找出什么问题了。那它应该怎么去执行呢？这里只说一下思路，就不贴代码了。可以使用eval或者Function来调用，还可以继续将这个代码进行编码来躲避浏览器的检查。

四、使用注释生成文档JSDoc

多行注释用来说明类和方法，这其中有什么讲究吗？

如果有同学有过Java的开发经验，就会知道，在Java中，可以用多行注释加上一些规定的格式写文档注释。简单的例子如下：

/**
* 这个类演示了文档注释
* @author Ayan Amhed
* @version 1.2
*/
public class SquareNum {

   /**
   * This method demonstrates square().
   * @param args Unused.
   * @return Nothing.
   */
   public static void main(String args[]) throws IOException
   {
      System.out.println("Squared value is " + val);
   }
}

通过这些注释，我们可以很快理解到这个class的作者、代码版本、方法参数、返回值这些信息。并且，如果在别的地方使用到这个方法或类，鼠标放上去的时候就可以看到注释的内容。这都是可以提高开发效率、保证正确率的。

Java里有强大的文档注释，那JavaScript呢？

JavaScript本身是没有这个功能的，不过有人开发一个这样的库，那就是JSDoc。它的用法非常的简单，就是在方法和类上添加这些带参数的注释。不过JSDoc是需要使用npm来安装的，并不支持传统的js开发方式。但这并不影响你养成这样的习惯。

JSDoc官方文档有一个这样的例子，用法和JavaDoc确实非常像。不过本文就不说明这个库的安装和使用方式了，各位读者请参考官方网站。

/**
 * Represents a book.
 * @constructor
 * @param {string} title - The title of the book.
 * @param {string} author - The author of the book.
 */
function Book(title, author) {
}

JSDoc的好处其实没有那么的直接，毕竟不像设计模式，代码技巧那些，会对项目直接产生影响。它主要是为工程化服务的，本人能想到的好处如下：