問(wèn)題描述

欲了解JSDoc所帶來(lái)的作用

比如這個(gè)文件: https://github.com/showdownjs...

我自己想到的:

讓 js 的接口, 變得靜態(tài) (其實(shí)主要是 3 )

方便生成文檔

方便 IDE , 同時(shí)也是方便調(diào)用接口的開(kāi)發(fā)者

那么還會(huì)有哪些實(shí)際的好處?

問(wèn)題解答

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

在文檔生成方面，JSDoc 確實(shí)可實(shí)現(xiàn)快捷的文檔生成。但這對(duì)代碼模塊的組織模式、注釋的長(zhǎng)度和開(kāi)發(fā)者的水平都有更高的要求，且自動(dòng)生成的文檔通?？勺x性不如直接維護(hù)的來(lái)得好（反例如 Yeoman，自動(dòng)生成的文檔一大半在處理莫名其妙的繼承關(guān)系）。

在提升開(kāi)發(fā)體驗(yàn)方面，編寫 JSDoc 確實(shí)能夠提高 IDE 進(jìn)行代碼提示的智能程度，也能夠配合 eslint 在開(kāi)發(fā) / 編譯（打包）階段發(fā)現(xiàn)潛在的問(wèn)題。

追加一點(diǎn)，在重構(gòu)代碼時(shí)，經(jīng)常遇到的一個(gè)問(wèn)題是【在運(yùn)行到這里時(shí)，這個(gè)變量應(yīng)該是什么類型，這種狀態(tài)下取什么值？】由于前端和后端實(shí)際上都是在圍繞數(shù)據(jù)編程，因此若使用非常動(dòng)態(tài)的數(shù)據(jù)類型且缺乏文檔，那么在維護(hù)或重構(gòu)代碼時(shí)，會(huì)發(fā)現(xiàn)經(jīng)常難以理解【函數(shù)到底輸入了什么，返回了什么】，而 JSDoc 可以有效改善這一點(diǎn)。

不過(guò)，個(gè)人猜測(cè)題主真正想問(wèn)的是：【既然 JSDoc 有這么多好處，是否應(yīng)該在我的業(yè)務(wù)代碼中使用這一功能呢？】

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

簡(jiǎn)單說(shuō)，JSDoc 造輪子時(shí)就上，業(yè)務(wù)代碼早點(diǎn)干完不加班最重要，不要自找麻煩。