简述 📑
受支持的平台: Windows (Windows 7 SP1 及以上版本)
为VSCode提供简易的代码注释自动化功能。
支持为C/C++项目提供智能注释生成、注释格式化、批量处理、文档导出等功能。
功能特性 🎉
- ✨ 智能注释生成 - 自动识别函数、类、结构体等代码元素，生成标准化注释
- 🎨 代码风格格式化 - 统一规范代码和注释风格，提升代码可读性
- 📝 注释自动补全 - 智能补全缺失的注释字段和参数说明
- 🔄 注释重建功能 - 快速重建或更新现有注释结构
- 🗑️ 注释删除功能 - 批量删除选定代码的注释内容
- 🏷️ 代码修改标记 - 自动生成增加、修改、删除等代码变更标记
- 📄 API文档导出 - 一键导出函数接口文档，支持markdown和word格式
- 🔧 批量处理工具 - 支持对多个文件进行批量注释处理
- ⚙️ 自定义模板 - 灵活配置注释模板，满足团队规范要求
- 🌍 多编码支持 - 自动检测和适配UTF-8、UTF-16等多种文件编码
支持的文件类型 📋
| 序号 |
文件扩展名 |
说明 |
| 1 |
.c |
C语言源文件 |
| 2 |
.cpp / .c++ / .cc / .cxx |
C++源文件 |
| 3 |
.h |
C/C++头文件 |
| 4 |
.inc |
包含文件 |
快速开始 🏃♀️
安装插件
- 在VSCode扩展市场搜索 "free comment tools"或使用free-comment-tools-xxx.vsix离线安装包
- 安装完成后重新启动VSCode，打开任意C/C++源代码文件（
.c、.cpp、.h等）
- 在VSCode代码编辑窗口点击右键，出现如下菜单项则安装成功
| 菜单名称 |
| ---------------- |
| 格式代码风格 |
| 补全代码注释 |
| 重建代码注释 |
| 删除代码注释 |
| 生成增加标记 |
| 生成修改标记 |
| 生成删除标记 |
| 导出函数接口文档 |
| 批量文件注释处理 |
| 配置代码注释模板 |
| 插件使用指导文档 |
基本使用
- 打开任意C/C++源代码文件（
.c、.cpp、.h等）
- 选中需要添加注释的代码块（可以是函数、类、结构体等）
- 右键打开上下文菜单，选择所需的注释功能
- 插件将自动生成符合规范的注释
功能详解 💡
功能说明： 对选中的代码块进行格式化处理，统一代码和注释的风格规范。
使用方法：
- 选中需要格式化的代码
- 右键菜单 → "格式代码风格"
- 代码将按照uncrustify配置进行格式化
适用场景：
- 统一团队代码风格
- 规范化注释格式
- 代码审查前的整理
功能说明： 智能分析代码结构，自动补全缺失的注释字段。
使用方法：
- 选中包含不完整注释的代码
- 右键菜单 → "补全代码注释"
- 自动补全函数参数、返回值等注释
适用场景：
- 为现有注释添加缺失字段
- 补充参数说明
- 完善返回值描述
示例：
// 补全前
int add(int a, int b) {
return a + b;
}
// 补全后
/**
* @fn add
* @brief 计算两数之和
* @param a 第一个加数
* @param b 第二个加数
* @return 两数之和
*
* @author YourName
* @date 2025-10-09
*/
int add(int a, int b) {
return a + b;
}
功能说明： 根据代码结构重新生成完整的注释模板。
使用方法：
- 选中需要添加注释的代码
- 右键菜单 → "重建代码注释"
- 在代码上方生成完整的注释模板
适用场景：
- 为新编写的函数添加注释
- 重新生成损坏的注释
- 快速创建标准化注释
支持的代码元素：
- 函数 (Function)
- 类 (Class)
- 结构体 (Struct)
- 联合体 (Union)
- 枚举 (Enum)
- 宏定义 (Define)
- 全局变量 (Global Variable)
功能说明： 批量删除选中代码范围内的所有注释。
使用方法：
- 选中包含注释的代码
- 右键菜单 → "删除代码注释"
- 所有注释将被移除
适用场景：
- 清理过时的注释
- 准备重新编写注释
- 代码重构时的清理工作
功能说明： 为新增的代码添加变更标记，记录修改人和修改时间。
使用方法：
- 选中新增的代码块
- 右键菜单 → "生成增加标记"
- 自动在代码前后添加增加标记
生成示例：
// add by YourName, time:2025-10-09 14:30:00
// reason: 添加新功能模块
void newFunction() {
// your code here
}
// add end
适用场景：
- 代码审查时标记新增内容
- 版本管理中追踪代码变更
- 团队协作中记录修改信息
功能说明： 为修改的代码添加修改标记。
使用方法：
- 选中修改的代码块
- 右键菜单 → "生成修改标记"
- 自动添加修改标记注释
生成示例：
// modify by YourName, time:2025-10-09 14:35:00
// reason: 优化算法性能
void existingFunction() {
// modified code
}
// modify end
功能说明： 为删除的代码添加删除标记，并将代码注释化。
使用方法：
- 选中需要标记为删除的代码
- 右键菜单 → "生成删除标记"
- 代码将被注释并添加删除标记
生成示例：
// delete by YourName, time:2025-10-09 14:40:00
// reason: 功能已废弃
// void oldFunction() {
// // old code
// }
// delete end
适用场景：
- 临时禁用某段代码
- 标记待删除的遗留代码
- 代码演进过程的记录
8. 导出函数接口文档 (Export API Document)
功能说明： 根据代码注释自动生成API接口文档。
使用方法：
- 选中包含函数注释的代码
- 右键菜单 → "导出函数接口文档"
- 自动生成结构化的接口文档
适用场景：
- 生成项目API文档
- 创建函数使用说明
- 准备技术文档材料
功能说明： 对多个文件进行批量注释处理。
使用方法：
- 右键菜单 → "批量文件注释处理"
- 在弹出的界面中选择文件和处理选项
- 批量执行注释操作
适用场景：
- 项目初始化时添加文件头注释
- 统一处理整个项目的注释格式
- 批量更新注释信息
10. 配置代码注释模板 (Setting Template)
功能说明： 自定义各类代码元素的注释模板。
使用方法：
- 右键菜单 → "配置代码注释模板"
- 在配置界面修改注释模板
- 保存后立即生效
可配置的模板：
- 文件头注释模板 (
file_header_comment.txt)
- 函数注释模板 (
func_header_comment.txt)
- 类注释模板 (
class_header_comment.txt)
- 结构体注释模板 (
struct_header_comment.txt)
- 联合体注释模板 (
union_header_comment.txt)
- 枚举注释模板 (
enum_header_comment.txt)
- 宏定义注释模板 (
define_header_comment.txt)
- 全局变量注释模板 (
global_var_header_comment.txt)
11. 插件使用指导文档 (Help Document)
功能说明： 打开详细的插件使用指导文档。
使用方法：
- 右键菜单 → "插件使用指导文档"
- 自动打开PDF帮助文档
注释模板配置 ⚙️
模板变量
注释模板中的特殊变量（由插件自动识别代码并填充）：
| 变量名 |
说明 |
适用范围 |
$(name) |
函数/类/变量名称 |
所有代码元素 |
$(filename) |
文件名 |
文件头注释 |
$(author) |
作者 |
所有模板 |
$(time) |
时间 |
所有模板 |
$(date) |
日期 |
所有模板 |
$(datetime) |
日期时间 |
所有模板 |
$(year) |
年份 |
所有模板 |
$(param) |
函数参数列表 |
函数注释 |
$(return) |
返回值说明 |
函数注释 |
自定义模板示例
函数注释模板：
/**
* @fn $(name)
* @brief [简要描述函数功能]
* $(param)
* $(return)
*
* @author $(author)
* @date $(date)
*/
文件头注释模板：
/**
* @file $(filename)
* @brief [一句话描述文件用途]
* @details [详细描述文件内容]
*
* @author $(author)
* @date $(date)
* @version V1.0.0
*
* @copyright Copyright (c) $(year) [Company/Organization]
*/
工作原理 🔧
该插件基于以下技术实现：
- 代码解析引擎 - 使用
FreeCommentPlugin.exe核心引擎解析C/C++代码结构
- 格式化工具 - 集成
uncrustify进行代码风格统一
- 模板系统 - 支持灵活的注释模板配置
- 编码处理 - 自动检测和适配多种文件编码（UTF-8/UTF-16）
- VSCode API集成 - 深度集成VSCode编辑器功能
快捷键设置 ⌨️
虽然插件默认不绑定快捷键，但你可以通过VSCode设置自定义快捷键：
- 打开命令面板（
Ctrl+Shift+P）
- 输入 "Preferences: Open Keyboard Shortcuts"
- 搜索 "free.ruex.cscomments"
- 为常用命令设置快捷键
推荐快捷键配置：
- 补全代码注释：
Ctrl+Alt+C
- 重建代码注释：
Ctrl+Alt+N
- 格式代码风格：
Ctrl+Alt+F
常见问题 ❓
Q1: 插件为什么只支持Windows平台？
A: 插件依赖的核心引擎FreeCommentPlugin.exe是Windows专用工具，因此目前仅支持Windows平台。
Q2: 如何修改注释模板的默认内容？
A: 在代码文件中右键选择"配置代码注释模板"，可以打开配置界面修改各类注释模板。修改后的模板立即生效。
Q3: 可以自定义注释风格吗？
A: 可以。通过菜单【配置代码注释模板】修改注释模板，可以完全自定义注释的格式和风格。
Q4: 批量处理功能如何使用？
A: 右键菜单选择"批量文件注释处理"，在弹出的工具界面中选择需要处理的文件和操作类型，可以一次性处理多个文件。
