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

浮生若梦的编程
  • 2.8k

实际现象

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

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

预期现象

我自己想到的:

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

  2. 方便生成文档

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

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

回复
阅读 4.1k
2 个回答
✓ 已被采纳

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

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

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

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

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

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

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

zzlw
  • 2
新手上路,请多包涵

写的很有道理!

撰写回答
你尚未登录,登录后可以
  • 和开发者交流问题的细节
  • 关注并接收问题和回答的更新提醒
  • 参与内容的编辑和改进,让解决方法与时俱进
宣传栏