代碼中注釋是不可少的,即使是自己寫的代碼,過了一段時(shí)間之后再重看,如果沒有注釋記錄的話,可能會(huì)想不到當(dāng)初是這樣實(shí)現(xiàn)的,尤其是在業(yè)務(wù)邏輯比較復(fù)雜的項(xiàng)目,注釋變得尤為重要。怎么優(yōu)雅的寫有用的注釋呢?
Sublime注釋插件-DocBlockr
功能
生成優(yōu)美注釋
簡(jiǎn)介
標(biāo)準(zhǔn)的注釋,包括函數(shù)名、參數(shù)、返回值等,并以多行顯示,省去手動(dòng)編寫
wiki
- https://github.com/spadgos/sublime-jsdocs
- https://sublime.wbond.net/packages/DocBlockr
使用方法
1.快速注釋: 輸入/*、/**(在Coffee-Script中是###*),Enter


2. 函數(shù)注釋:使用Tab在不同的字段切換



3. 變量注釋

4. 注釋+評(píng)論




注釋規(guī)范
目前腳本、樣式的注釋格式都有一個(gè)已經(jīng)成文的約定規(guī)范,最初是YUI Compressor制定。
|
1
2
3
4
5
6
7
8
|
/**
* 這里的注釋內(nèi)容【會(huì)】被壓縮工具壓縮
*/
/*!
* 這里的注釋內(nèi)容【不會(huì)】被壓縮工具壓縮
* 與上面一個(gè)注釋塊不同的是,第2個(gè)*換成了!
*/
|
其中說到這里說到的壓縮工具有YUI Compressor 、Google Closure Compiler、gulp-uglify、grunt-contrib-uglify等,這些壓縮工具都支持以上的壓縮約定。常常把文件的關(guān)鍵信息放在第2種注釋內(nèi)容里,如文件名稱、版本號(hào)、作者等。
關(guān)于這些關(guān)鍵信息,都由一些關(guān)鍵詞和一定的格式來書寫。關(guān)鍵詞書寫格式為:
|
1
2
3
4
|
/**
* @author ydr.me
* @version 1.0
*/
|
使用@key desc格式來書寫,常用的關(guān)鍵詞有:
| 關(guān)鍵詞 | 描述 |
|---|---|
| @auhor | 作者 |
| @param | 參數(shù) |
| @example | 示例 |
| @link | 鏈接 |
| @namespace | 命名空間 |
| @requires | 依賴模塊 |
| @return | 返回值 |
| @version | 版本號(hào) |
其中,param關(guān)鍵詞的格式為:
|
1
2
3
|
/**
* @param {String} 參數(shù)描述
*/
|

