demoshop

寫 Web 的開發者絕對逃不了 JavaScript ，因為 JavaScript 的程式量不小，所以適時的加上註解是一件很重要的事，可以讓其他成員在叫用的時候可以更明確的了解應該怎麼用這個方法，這裡介紹一個套件讓開發人員可以輕鬆上註解，造福人群也造福自己（通常你亂亂寫後來要維護的還是你自己）。

多年前 demo 寫過了一篇「如何讓自己寫的 JS 也擁有 tooltip (註解)」，那時候因為沒有工具支援所以完全是有「愛」才能堅持下去，現在不一樣啦 Visual Studio 自從開放使用者自行開發套件以後，很多「生產力」工具就逐一冒出，讓開發人員寫 JavaScript 註解不在是一件麻煩的事情。

 

假設我們先來寫一個 js function

function test(a, b, c) {
    if (a===b) {
        alert(c);
    }
}

(不要問我在寫啥，我也不知道）

---

當需要使用到該方法時，開發者完全不知到這方法能幹啥

如果能寫上註解，那一切都不一樣了

/**
 * 測試用方法
 * @param a 基準值
 * @param b 比較值
 * @param c 當基準值與比較值相等時會跳出此參數的內容值
 */
function test(a, b, c) {
    if (a===b) {
        alert(c);
    }
}

 

自己打註解是很累的，只要您的 Visual Studio 版本是 2013 以上就可以下載 DocStubsJs 擴充功能。

---

上述的註解格式為 jsdoc 您可以利用在方法上方輸入 /** 自動產出

基本框架產生後，就填入需要的註解說明吧，依據上方範例示範，輸入中文也是沒有問題的。

---

如果您需要使用 vsdoc 的註解可以改在 function 內輸入 ///

---

但是如果您同時寫了 vsdoc 以及 jsdoc 的話，那 Intellisense 會選擇顯示 vsdoc 的內容，這可能要注意一下，不過 jsdoc 已經算是一個標準了（非官方）所以建議寫 jsdoc 即可，還有一點 jsdoc 是可以增加參數的型別顯示，讓叫用者方便的使用。

/**
 * 測試用方法
 * @param {string} a 基準值
 * @param {string} b 比較值
 * @param {string} c 當基準值與比較值相等時會跳出此參數的內容值
 */
function test(a, b, c) {
    if (a===b) {
        alert(c);
    }
}

注意看上圖，參數已經不是 Object 了，可惜的是目前此套件尚未支援自動產出 type 部分讓我們修改，所以每次都要手動加上去。

---

不過如果您有 Resharper 的話就可以直接產出包含 Type 的註解範本

P.S.  twMVC 活動不定期會送出價值超過三萬的 Resharper 唷。

P.S. 如果希望專案內的 JavaScript 可以更結構化更物件導向，demo 強烈推薦使用 TypeScript 開發，可惜的是此套件目前尚未支援 TypeScript 註解 （但 Resharper 可以）