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

实际现象

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

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

预期现象

我自己想到的:

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

  2. 方便生成文档

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

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

阅读 2.6k
评论 2017-05-23 提问
    2 个回答
    ewind
    • 1.9k

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

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

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

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

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

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

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

    评论 赞赏
      zzlw
      • 2
      • 新人请关照

      写的很有道理!

      评论 赞赏
        撰写回答

        登录后参与交流、获取后续更新提醒