在 VS Code 中配置自定义注释模板可以极大提升代码注释效率（尤其是函数、类、文件头部等高频注释场景）。核心通过 用户代码片段（User Snippets） 实现，支持自定义触发词、自动填充变量（如日期、文件名），且可按语言区分模板。以下是详细步骤和示例：

 

一、基础：通过「用户代码片段」配置模板

 

1. 打开代码片段配置界面

 

路径：

 文件（File）→ 首选项（Preferences）→ 配置用户代码片段（Configure User Snippets） 

（快捷键：Windows/Linux 按  Ctrl+Shift+P ，Mac 按  Cmd+Shift+P ，输入  snippets  选择对应选项）

 

选择配置范围：

 

- 全局模板：选择  New Global Snippets file （所有语言通用），命名为  global.json  等。

​

- 语言特定模板：选择对应语言（如  javascript.json 、 python.json ），仅在该语言文件中生效（推荐，因不同语言注释风格不同）。

 

2. 代码片段结构说明

 

每个模板是一个 JSON 对象，核心字段：

{

  "模板名称": {

    "prefix": "触发词", // 输入该词后按 Tab 触发模板

    "body": [ // 模板内容（数组元素为每行内容）

      "注释行1",

      "注释行2：$1", // $1 是光标初始位置，按 Tab 可跳转到 $2、$3...

      "注释行3：${2:默认值}" // 带默认值的光标位置

    ],

    "description": "模板描述" // 显示在智能提示中的说明

  }

}

关键变量（自动填充动态信息）：

 

-  $CURRENT_YEAR / $CURRENT_MONTH / $CURRENT_DATE ：当前年月日

​

-  $TM_FILENAME ：当前文件名

​

-  $TM_AUTHOR ：作者（需在 VS Code 配置中设置，路径：首选项→设置→搜索  author ）

​

-  $1 / $2 ：光标位置（按 Tab 切换）， $0  为最终停留位置

​

-  \t / \n ：制表符/换行符（在字符串中用转义字符）

 

二、实用模板示例（按场景分类）

 

1. 文件头部注释（通用模板）

 

适用于所有文件，包含文件名、创建时间、作者、描述等。

配置（以全局模板  global.json  为例）：

{

  "File Header": {

    "prefix": "header", // 输入 header 按 Tab 触发

    "body": [

      "/**",

      " * @file ${TM_FILENAME}", // 自动填充当前文件名

      " * @description ${1:文件功能描述}", // 光标先停在这里输入描述

      " * @author ${TM_AUTHOR}", // 作者（需提前设置）

      " * @createTime ${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE} ${CURRENT_HOUR}:${CURRENT_MINUTE}", // 创建时间

      " * @updateTime ${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE} ${CURRENT_HOUR}:${CURRENT_MINUTE}", // 更新时间（可手动修改）

      " */",

      "$0" // 最终光标停在这里

    ],

    "description": "文件头部注释模板"

  }

}

2. 函数注释（JavaScript/TypeScript）

 

符合 JSDoc 规范，包含参数、返回值、描述等。

配置（在  javascript.json  中）：

{

  "Function Comment": {

    "prefix": "fn", // 输入 fn 按 Tab 触发

    "body": [

      "/**",

      " * @description ${1:函数功能描述}",

      " * @param {${2:type}} ${3:paramName} - ${4:参数说明}", // 按 Tab 依次填写类型、参数名、说明

      " * @returns {${5:type}} ${6:返回值说明}",

      " * @author ${TM_AUTHOR}",

      " */",

      "function ${7:functionName}($3) {",

      " $0", // 函数体光标位置

      "}"

    ],

    "description": "JavaScript 函数注释模板"

  }

}

3. 类注释（Python）

 

符合 Python 文档字符串规范，包含类描述、属性、方法说明。

配置（在  python.json  中）：

{

  "Class Comment": {

    "prefix": "cls", // 输入 cls 按 Tab 触发

    "body": [

      "\"\"\"",

      "类名：${1:ClassName}",

      "描述：${2:类的功能说明}",

      "属性：",

      " - ${3:attr1}: ${4:属性1说明}",

      "方法：",

      " - ${5:method1}: ${6:方法1说明}",

      "创建者：${TM_AUTHOR}",

      "创建时间：${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE}",

      "\"\"\"",

      "class $1:",

      " def __init__(self):",

      " $0" // 构造函数光标位置

    ],

    "description": "Python 类注释模板"

  }

}  

三、使用方法

 

1. 在对应文件中输入模板的  prefix （如  header 、 fn ）；

​

2. 按  Tab  键触发模板，光标会自动跳到  $1  位置；

​

3. 填写内容后，按  Tab  切换到下一个光标位置（ $2 、 $3 ...），最终停在  $0 。

 

四、进阶：用扩展增强功能

 

如果需要更复杂的注释（如自动更新修改时间、批量生成），推荐扩展 koroFileHeader：

 

1. 安装：VS Code 扩展商店搜索  koroFileHeader  并安装。

​

2. 配置：右键 →  设置文件头部注释 / 设置函数注释 ，自定义模板（支持更多变量和快捷键）。

​

3. 快捷键：

​

- 文件头部注释： Ctrl+Alt+i （Windows）/  Cmd+Option+i （Mac）

​

- 函数注释： Ctrl+Alt+t （Windows）/  Cmd+Option+t （Mac）