vscode注释插件「koroFileHeader」

前言

在vscode上进行前端开发，有几个流行的注释插件：

• Better Comments
• Todo Tree
• koroFileHeader
• Document This
• Auto Comment Blocks

在上面的插件中我选择 koroFileHeader 做推荐，原因一是使用人数比较多（最多的是 Better Comments ），二是它能做文件头部注释和函数注释，注释模块可配置。头部注释可自动更新最后编辑人

安装

在vscode扩展商店中搜索 koroFileHeader ，点击安装

快捷键使用

文件头部注释：

window：ctrl+win+i
mac：ctrl+cmd+i
linux: ctrl+meta+i

函数注释：将光标放在函数上方的空白行

window：ctrl+win+t
mac：ctrl+cmd+t
linux: ctrl+meta+t

快捷键注释不可用的问题：参考这里

注释模版配置

打开全局配置（setting.json），进行必要的基础配置

// 头部注释
"fileheader.customMade": {
    // Author字段是文件的创建者 可以在specialOptions中更改特殊属性
    // 自动提取当前git config中的: 用户名、邮箱
    "Author": "git config user.name && git config user.email", // 同时获取用户名与邮箱
    // "Author": "git config user.name", // 仅获取用户名
    // "Author": "git config user.email", // 仅获取邮箱
    // "Author": "OBKoro1", // 写死的固定值 不从git config中获取
    "Date": "Do not edit", // 文件创建时间(不变)
    // LastEditors、LastEditTime、FilePath将会自动更新 如果觉得时间更新的太频繁可以使用throttleTime(默认为1分钟)配置更改更新时间。
    "LastEditors": "git config user.name && git config user.email", // 文件最后编辑者 与Author字段一致
    // 由于编辑文件就会变更最后编辑时间，多人协作中合并的时候会导致merge
    // 可以将时间颗粒度改为周、或者月，这样冲突就减少很多。搜索变更时间格式: dateFormat
    "LastEditTime": "Do not edit", // 文件最后编辑时间
    // 输出相对路径，类似: /文件夹名称/src/index.js
    "FilePath": "Do not edit", // 文件在项目中的相对路径 自动更新
    // 插件会自动将光标移动到Description选项中 方便输入 Description字段可以在specialOptions更改
    "Description": "", // 介绍文件的作用、文件的入参、出参。
},
// 函数注释
"fileheader.cursorMode": {
    "description": "", // 函数注释生成之后，光标移动到这里
    "param": "", // param 开启函数参数自动提取 需要将光标放在函数行或者函数上方的空白行
    "return": "",
}

插件配置项

详细的配置：参考这里

常用的配置：

// 插件配置项
"fileheader.configObj": {
    "autoAdd": true, // 检测文件没有头部注释，自动添加文件头部注释，配合头部注释黑名单使用更佳
    "autoAddLine": 100, // 文件超过多少行数 不再自动添加头部注释
    "autoAlready": true, // 只添加插件支持的语言以及用户通过`language`选项自定义的注释
    "supportAutoLanguage": ["js", "vue"], // 设置之后，在数组内的文件才支持自动添加
    "prohibitAutoAdd": ["json", "md"], // 自动添加头部注释黑名单
    "prohibitItemAutoAdd": [ "项目的全称禁止项目自动添加头部注释, 使用快捷键自行添加" ],
    "folderBlacklist": [ "node_modules" ], // 文件夹或文件名禁止自动添加头部注释
    "wideSame": false, // 头部注释等宽设置
    "wideNum": 13,  // 头部注释字段长度 默认为13
    "functionWideNum": 0, // 函数注释等宽设置 设为0 即为关闭
    "dateFormat": "YYYY-MM-DD HH:mm:ss", // 时间格式
    "CheckFileChange": false, // 单个文件保存时进行diff检查，默认false
    "createHeader": true, // 新建文件自动添加头部注释
    "throttleTime": 60000, // 对同一个文件 需要过1分钟再次修改文件并保存才会更新注释
}

• 单个文件保存时进行diff检查 「CheckFileChange」

每次保存之后，会进行一次diff检查, 如果文件只变更了LastEditors/LastEditTime，该文件将会回滚到本地仓库的最新版本
使用场景：对文件进行修改之后又撤销，但是LastEditors和LastEditTime已经变更了，在提交代码的时候很容易忘记恢复它，导致无意义的提交

运行逻辑：

1. 检测VSCode当前打开的文件夹的根目录是否有.git文件夹, 没有的话，则退出
2. 获取触发保存文件的diff，进行diff检查
3. 检测当只有LastEditors和LastEditTime变更，其他任何变更都没有的情况下
4. 将该文件回滚到本地仓库的最新版本

推荐配置

    // 头部注释
    "fileheader.customMade": {
        "Author": "git config user.email", // 同时获取用户名与邮箱
        "Date": "Do not edit", // 文件创建时间(不变)
        "LastEditors": "git config user.email", // 文件最后编辑者 与Author字段一致
        // 由于编辑文件就会变更最后编辑时间，多人协作中合并的时候会导致merge
        // 可以将时间颗粒度改为周、或者月，这样冲突就减少很多。搜索变更时间格式: dateFormat
        "LastEditTime": "Do not edit", // 文件最后编辑时间
        "FilePath": "Do not edit", // 文件在项目中的相对路径 自动更新
        "Description": "", // 介绍文件的作用、文件的入参、出参。
    },
    // 函数注释
    "fileheader.cursorMode": {
        "description": "", // 函数注释生成之后，光标移动到这里
        "param": "", // param 开启函数参数自动提取 需要将光标放在函数行或者函数上方的空白行
        "return": "",
    },
    // 插件配置项
    "fileheader.configObj": {
        "prohibitAutoAdd": ["json", "md"], // 自动添加头部注释黑名单
        "folderBlacklist": [ "node_modules", "dist" ], // 文件夹或文件名禁止自动添加头部注释
        "wideSame": true, // 头部注释等宽设置
        "wideNum": 13,  // 头部注释字段长度 默认为13
        "functionWideNum": 13, // 函数注释等宽设置 设为0 即为关闭
        "dateFormat": "YYYY-MM-DD HH:mm", // 时间格式
        "CheckFileChange": true, // 单个文件保存时进行diff检查
        "createHeader": true, // 新建文件自动添加头部注释
        "throttleTime": 60000, // 对同一个文件 需要过1分钟再次修改文件并保存才会更新注释
    }

Better Comments 扩展

• 安装

• 使用，正常注释，前面使用相应的前缀即可，插件自带5种高亮注释

// ! 红色的高亮注释
// ? 蓝色的高亮注释
// * 绿色的高亮注释
// todo 橙色的高亮注释
// // 灰色带删除线的注释
// 普通的注释

• 自带的高亮注释不好看的话是可以自定义的，在 settings.json 文件里配置

    "better-comments.tags": [
        {
          "tag": "!", // 符号标识
          "color": "#3498DB", // 注释颜色
          "strikethrough": false, // 是否添加删除线
          "backgroundColor": "transparent" // 背景颜色
        },
        {
          "tag": "?",
          "color": "#3498DB",
          "strikethrough": false,
          "backgroundColor": "transparent"
        },
        {
          "tag": "//",
          "color": "#474747",
          "strikethrough": true,
          "backgroundColor": "transparent"
        },
        {
          "tag": "todo",
          "color": "#FF8C00",
          "strikethrough": false,
          "backgroundColor": "transparent"
        },
        {
          "tag": "*",
          "color": "#98C379",
          "strikethrough": false,
          "backgroundColor": "transparent"
        }
    ]

• 也可以自定义自己想要的高亮注释

    {
        "tag": "my",
        "color": "#d0db45",
        "strikethrough": false,
        "backgroundColor": "transparent"
    }