前言
代码中注释是不可少的,即使是自己写的代码,过了一段时间之后再重看,如果没有注释记录的话,可能会想不到当初是这样实现的,尤其是在业务逻辑比较复杂的项目,注释变得尤为重要。怎么优雅的写有用的注释呢?
Sublime注释插件-DocBlockr
功能
生成优美注释
简介
标准的注释,包括函数名、参数、返回值等,并以多行显示,省去手动编写
wiki
使用方法
1.快速注释: 输入/*、/**(在Coffee-Script中是###*),Enter
2. 函数注释:使用Tab在不同的字段切换
3. 变量注释
4. 注释+评论
注释规范
目前脚本、样式的注释格式都有一个已经成文的约定规范,最初是YUI Compressor制定。
1 2 3 4 5 6 7 8 | /** * 这里的注释内容【会】被压缩工具压缩 */ /*! * 这里的注释内容【不会】被压缩工具压缩 * 与上面一个注释块不同的是,第2个*换成了! */ |
其中说到这里说到的压缩工具有 、、、等,这些压缩工具都支持以上的压缩约定。常常把文件的关键信息放在第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} 参数描述 */ |