前言
代碼中注釋是不可少的，即使是自己寫的代碼，過了一段時間之后再重看，如果沒有注釋記錄的話，可能會想不到當初是這樣實現的，尤其是在業務邏輯比較復雜的項目，注釋變得尤為重要。怎么優雅的寫有用的注釋呢？
Sublime注釋插件-DocBlockr
功能
生成優美注釋
簡介
標准的注釋，包括函數名、參數、返回值等，並以多行顯示，省去手動編寫
wiki
使用方法
1.快速注釋： 輸入/*、/**（在Coffee-Script中是###*），Enter
2. 函數注釋：使用Tab在不同的字段切換
3. 變量注釋
4. 注釋+評論
注釋規范
目前腳本、樣式的注釋格式都有一個已經成文的約定規范，最初是YUI Compressor制定。
|
1
2
3
4
5
6
7
8
|
/**
* 這里的注釋內容【會】被壓縮工具壓縮
*/
/*！
* 這里的注釋內容【不會】被壓縮工具壓縮
* 與上面一個注釋塊不同的是，第2個*換成了!
*/
|
其中說到這里說到的壓縮工具有YUI Compressor 、Google Closure Compiler、gulp-uglify、grunt-contrib-uglify等，這些壓縮工具都支持以上的壓縮約定。常常把文件的關鍵信息放在第2種注釋內容里，如文件名稱、版本號、作者等。
關於這些關鍵信息，都由一些關鍵詞和一定的格式來書寫。關鍵詞書寫格式為：
|
1
2
3
4
|
/**
* @author ydr.me
* @version 1.0
*/
|
使用@key desc格式來書寫，常用的關鍵詞有：
| 關鍵詞 | 描述 |
|---|---|
@auhor |
作者 |
@param |
參數 |
@example |
示例 |
@link |
鏈接 |
@namespace |
命名空間 |
@requires |
依賴模塊 |
@return |
返回值 |
@version |
版本號 |
其中，param關鍵詞的格式為：
|
1
2
3
|
/**
* @param {String} 參數描述
*/
|