問題描述

欲了解JSDoc所帶來的作用

比如這個文件: https://github.com/showdownjs...

我自己想到的:

讓 js 的接口, 變得靜態 (其實主要是 3 )

方便生成文檔

方便 IDE , 同時也是方便調用接口的開發者

那么還會有哪些實際的好處?

問題解答

不管你寫不寫 JSDoc，JS 的接口都是非常動態的。函數同樣可以使用 arguments 和 call 等動態方法傳入各種不同的參數格式，甚至可以不匹配接收方的參數列表。

在文檔生成方面，JSDoc 確實可實現快捷的文檔生成。但這對代碼模塊的組織模式、注釋的長度和開發者的水平都有更高的要求，且自動生成的文檔通常可讀性不如直接維護的來得好（反例如 Yeoman，自動生成的文檔一大半在處理莫名其妙的繼承關系）。

在提升開發體驗方面，編寫 JSDoc 確實能夠提高 IDE 進行代碼提示的智能程度，也能夠配合 eslint 在開發 / 編譯（打包）階段發現潛在的問題。

追加一點，在重構代碼時，經常遇到的一個問題是【在運行到這里時，這個變量應該是什么類型，這種狀態下取什么值？】由于前端和后端實際上都是在圍繞數據編程，因此若使用非常動態的數據類型且缺乏文檔，那么在維護或重構代碼時，會發現經常難以理解【函數到底輸入了什么，返回了什么】，而 JSDoc 可以有效改善這一點。

不過，個人猜測題主真正想問的是：【既然 JSDoc 有這么多好處，是否應該在我的業務代碼中使用這一功能呢？】

這個問題和【我是否應該編寫單元測試】實際上是一類問題。大家都知道編寫單元測試和 JSDoc 有不少好處，但是問題也非常明顯：它們會增加代碼量和開發周期長度。和單元測試代碼在單獨的 test 目錄不同，JSDoc 直接增加了業務代碼長度（除非你使用 TypeScript spec 等新 Doc 手段）。因此實踐中對復用性不高的業務代碼，不寫 JSDoc 或單元測試是完全沒有問題的（答主在若干也不算小的廠混過日子，各家前端的實際業務代碼都是以實現功能為第一位，不寫成面條代碼就不錯了，哪里還有時間給你加啰嗦的文檔？當然了對后端這種基本以查表 - 返回數據為主的崗位，編寫 Doc 方面是更容易有各自的規范的）。而在你造輪子，發布一些可復用的代碼模塊時，完善的 JSDoc 和單元測試有利于模塊的可維護性，也能讓使用者感受到【代碼質量確實不錯】。

簡單說，JSDoc 造輪子時就上，業務代碼早點干完不加班最重要，不要自找麻煩。