前端注释工具的优雅使用指南

对于代码来说，注释是一个可以帮助我们快速理解代码含义、用法的好工具，今天我们就来盘一盘前端可以使用的优雅注释工具。

我们常用的注释分为文件头部注释和函数注释两种，一种描述文件，另一种描述函数。那么对应到我们前端使用率最高的两个IDE，webstorm和vscode来说分别是怎么操作的呢？（别问我为啥要写两个IDE,因为我两个都用！）

webstorm

文件头部注释

安装配置如下：

webstrom的头部注释是需要依赖它的liveTemplate来实现的，具体位置在Preferences(对于windows来说是Setting)/Editor/liveTemplates下，可以选择到任意一个文件夹下或者自建一个文件夹来做，点击右侧小加号，新建一个模板，例如我们起一个快捷代码叫desc：

在template text写入我们的模板内容：

/**
 * @author zhaosh
 * @description: $desc$
 * @date $date$ 
*/
1
2
3
4
5

这里需要自己写一个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" // 默认为随机图案 生成哪个注释图案
    }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

这里是一些常用的配置，如果想要配更多属性，可以参考作者配置文档，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
  
  
  1
  2
  3
  4
  5
  6
  7
  8
  9
  10

  效果如图：

  

• 函数注释

  window：ctrl+win+t
  
  mac：ctrl+cmd+t
  
  linux: ctrl+meta+t
  
  Ubuntu: ctrl+super+t
  1
  2
  3
  4
  5
  6
  7

  效果如图：

  

  小tips:

  可以获取到ts定义的参数类型，但是无法获取到ts定义的返回值类型

• 骚操作注释

  
  window：ctrl+alt+j
  
  mac：ctrl+cmd+j
  
  1
  2
  3
  4
  5

  效果如图：

  
  

  小tips：

  默认使用随机图案，如果想要选择你想要的图案可以快捷键shift+command+p 输入> 注释图案 或者是 > codeDesign就可以选择注释图案了， 如下图所示

  

快捷键口诀：

自己编了一个小口诀：

头部用 i ，函数用 t ，要说大佛，还得上 j ！