JsDoc有何很实际的具体作用?

Question

实际现象

1. 欲了解JSDoc所带来的作用

比如这个文件: https://github.com/showdownjs...

预期现象

我自己想到的:

1. 让 js 的接口, 变得静态 (其实主要是 3 )

2. 方便生成文档

3. 方便 IDE , 同时也是方便调用接口的开发者

那么还会有哪些实际的好处?

Answer 1

不管你写不写 JSDoc，JS 的接口都是非常动态的。函数同样可以使用 arguments 和 call 等动态方法传入各种不同的参数格式，甚至可以不匹配接收方的参数列表。

在文档生成方面，JSDoc 确实可实现快捷的文档生成。但这对代码模块的组织模式、注释的长度和开发者的水平都有更高的要求，且自动生成的文档通常可读性不如直接维护的来得好（反例如 Yeoman，自动生成的文档一大半在处理莫名其妙的继承关系）。

在提升开发体验方面，编写 JSDoc 确实能够提高 IDE 进行代码提示的智能程度，也能够配合 eslint 在开发 / 编译（打包）阶段发现潜在的问题。

追加一点，在重构代码时，经常遇到的一个问题是【在运行到这里时，这个变量应该是什么类型，这种状态下取什么值？】由于前端和后端实际上都是在围绕数据编程，因此若使用非常动态的数据类型且缺乏文档，那么在维护或重构代码时，会发现经常难以理解【函数到底输入了什么，返回了什么】，而 JSDoc 可以有效改善这一点。

不过，个人猜测题主真正想问的是：【既然 JSDoc 有这么多好处，是否应该在我的业务代码中使用这一功能呢？】

这个问题和【我是否应该编写单元测试】实际上是一类问题。大家都知道编写单元测试和 JSDoc 有不少好处，但是问题也非常明显：它们会增加代码量和开发周期长度。和单元测试代码在单独的 test 目录不同，JSDoc 直接增加了业务代码长度（除非你使用 TypeScript spec 等新 Doc 手段）。因此实践中对复用性不高的业务代码，不写 JSDoc 或单元测试是完全没有问题的（答主在若干也不算小的厂混过日子，各家前端的实际业务代码都是以实现功能为第一位，不写成面条代码就不错了，哪里还有时间给你加啰嗦的文档？当然了对后端这种基本以查表 - 返回数据为主的岗位，编写 Doc 方面是更容易有各自的规范的）。而在你造轮子，发布一些可复用的代码模块时，完善的 JSDoc 和单元测试有利于模块的可维护性，也能让使用者感受到【代码质量确实不错】。

简单说，JSDoc 造轮子时就上，业务代码早点干完不加班最重要，不要自找麻烦。

Answer 2

写的很有道理！