sublime注释插件与javascript注释规范

2015-12-30 15:32:48来源:轩枫阁 作者:

代码中注释是不可少的,即使是自己写的代码,过了一段时间之后再重看,如果没有注释记录的话,可能会想不到当初是这样实现的,尤其是在业务逻辑比较复杂的项目,注释变得尤为重要。怎么优雅的写有用的注释呢?

代码中注释是不可少的,即使是自己写的代码,过了一段时间之后再重看,如果没有注释记录的话,可能会想不到当初是这样实现的,尤其是在业务逻辑比较复杂的项目,注释变得尤为重要。怎么优雅的写有用的注释呢?

Sublime注释插件-Doc​Blockr

功能

生成优美注释

简介

标准的注释,包括函数名、参数、返回值等,并以多行显示,省去手动编写

wiki

  • https://github.com/spadgos/sublime-jsdocs
  • https://sublime.wbond.net/packages/DocBlockr

使用方法

1.快速注释: 输入/*、/**(在Coffee-Script中是###*),Enter

basic

687474703a2f2f73706164676f732e6769746875622e696f2f7375626c696d652d6a73646f63732f696d616765732f62617369632d626c6f636b2e676966

 

2. 函数注释:使用Tab在不同的字段切换

function-template

687474703a2f2f73706164676f732e6769746875622e696f2f7375626c696d652d6a73646f63732f696d616765732f6c6f6e672d617267732e676966

687474703a2f2f73706164676f732e6769746875622e696f2f7375626c696d652d6a73646f63732f696d616765732f747970652d68696e74696e672e676966

 

3. 变量注释

687474703a2f2f73706164676f732e6769746875622e696f2f7375626c696d652d6a73646f63732f696d616765732f766172732e676966

 

4. 注释+评论

safd

sdgfvsd

fdgfd

sdfgds

注释规范

目前脚本、样式的注释格式都有一个已经成文的约定规范,最初是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} 参数描述
*/