javascript - Was sind die praktischen und spezifischen Verwendungszwecke von JsDoc?

Question

Tatsächliches Phänomen

1. Um die Rolle von JSDoc zu verstehen

Zum Beispiel diese Datei: https://github.com/showdownjs...

Erwartetes Phänomen

Ich habe selbst darüber nachgedacht:

1. Lassen Sie die js-Schnittstelle 变得静态 (eigentlich hauptsächlich 3)

2. Einfach zu erstellende Dokumente

3. Praktisch für die IDE und auch praktisch für Entwickler zum Aufrufen von Schnittstellen

Was sind also die praktischen Vorteile?

Answer 1

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

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

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

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

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

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

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