对于代码来说,注释是一个可以帮助我们快速理解代码含义、用法的好工具,今天我们就来盘一盘前端可以使用的优雅注释工具。
我们常用的注释分为文件头部注释和函数注释两种,一种描述文件,另一种描述函数。那么对应到我们前端使用率最高的两个IDE,webstorm和vscode来说分别是怎么操作的呢?(别问我为啥要写两个IDE,因为我两个都用!)
webstorm
文件头部注释
安装配置如下:
webstrom的头部注释是需要依赖它的liveTemplate来实现的,具体位置在Preferences(对于windows来说是Setting)/Editor/liveTemplates下,可以选择到任意一个文件夹下或者自建一个文件夹来做,点击右侧小加号,新建一个模板,例如我们起一个快捷代码叫desc:
在template text写入我们的模板内容:
/**
* @author zhaosh
* @description: $desc$
* @date $date$
*/
这里需要自己写一个date模板格式化,否则默认的时间格式是不规范的:
然后保存选择应用的文件类型为全部,Apply+ok就完事了。
使用方法:
在页面头部输入desc:
按回车即可出现文件头部注释:
小tips:
细心的读者老爷已经发现了,这里会默认聚焦到了description上,直接输入描述即可,这是因为我们在模板内容那里写了$desc$
并放到了date上边,所以第一输入位置是description,第二输入位置是date
函数注释
函数注释就比较简单一点了,直接在函数上方一行输入/**
然后回车即可出现注释:
小tips:
第一行默认为空,其实是为了写函数解释说明;
/**
是用了JSDoc,对于js、jsx、tsx等文件类型都亲测有用,它可以获取到函数参数但不能获取到参数类型
vscode
vscode的强大之处在于它的插件众多,我们只需要选一款好用稳定的插件就可以了,这里推荐koroFileHeader,别问我列表这么多为什么推荐这款,问就是挨个试了一遍这个最好用且满足我的需求o
koroFileHeader优点列举:
- 下载使用量多,截止写文钱下载量高达336321次
- 同时支持文件头部注释与函数注释,且注释内容丰富可配
- 支持骚操作,想画个佛祖保佑永无bug、神兽护体做注释也是轻轻松松
安装配置如下:
先下载插件,下载后按command + ,
键打开设置,搜索fileheader
这里是可以配置的三个区域,可以直接点setting.json文件配置自己想要的:
customMade里配置头部注释内容,cursorMode里配置函数注释内容,configObj里配置骚操作内容,代码直接放出来:
//头部注释
"fileheader.customMade": {
"Author":"git config user.name",
"Date":"Do not edit",
"LastEditors":"git config user.name",
"LastEditTime":"Do not edit",
"Description":"file content"
},
// 函数注释
"fileheader.cursorMode": {
"description": "", // 函数注释生成之后,光标移动到这里
"param": "", // param 开启函数参数自动提取 需要将光标放在函数行或者函数上方的空白行
"return": "",
},
// 配置头部骚操作
"fileheader.configObj": {
"designAddHead": true, // 默认关闭, 生成的图案注释是否附带头部注释
"headDesignName": "random" // 默认为随机图案 生成哪个注释图案
}
这里是一些常用的配置,如果想要配更多属性,可以参考作者配置文档,https://github.com/OBKoro1/koro1FileHeader/wiki/%E9%85%8D%E7%BD%AE%E5%AD%97%E6%AE%B5
使用方法:
配完以后不要急,先把vscode重启下让配置生效再使用。
-
文件头部注释
window:ctrl+win+i mac:ctrl+cmd+i linux: ctrl+meta+i Ubuntu: ctrl+super+i
效果如图:
-
函数注释
window:ctrl+win+t mac:ctrl+cmd+t linux: ctrl+meta+t Ubuntu: ctrl+super+t
效果如图:
小tips:
可以获取到ts定义的参数类型,但是无法获取到ts定义的返回值类型
-
骚操作注释
window:ctrl+alt+j mac:ctrl+cmd+j
效果如图:
小tips:
默认使用随机图案,如果想要选择你想要的图案可以快捷键
shift+command+p
输入> 注释图案
或者是> codeDesign
就可以选择注释图案了, 如下图所示
快捷键口诀:
自己编了一个小口诀:
头部用 i ,函数用 t ,要说大佛,还得上 j !