CoDoc

一站式代码注释文档管理解决方案,助力团队高效实践"文档即代码"理念
🔍 什么是 CoDoc?
CoDoc (Code Documentation) 是一款专为开发团队设计的代码文档管理工具,它将代码注释与文档管理完美融合。通过结构化的注释标签系统,CoDoc 让开发者能在编写代码的同时生成高质量的技术文档,实现真正的"文档即代码"(Docs as Code)实践。
无论是需求实现的技术方案、关键设计决策,还是测试重点和问题修复记录,CoDoc 都能以统一的方式进行管理和展示,使团队成员轻松了解代码背后的思考过程和业务逻辑。
为什么选择 CoDoc?
- 无缝融入开发流程:直接在代码中编写文档,无需在代码和外部文档间切换
- 标准化文档模板 - 提供多种场景下的标准化注释模板,确保团队文档风格统一
- 可视化文档管理 - 集成文档树视图,直观展示和管理代码中的文档注释
- 多维度组织与管理 - 按需求、领域或文档类型灵活组织和查询文档
- 自动文档生成 - 自动提取代码注释,一键导出技术方案变更文档
- 高亮注释提示 - 集成注释高亮功能,提高代码文档可读性
📋 快速使用指南
1. 插入文档注释
在支持的编程语言文件中,输入以下任一触发词后按下 Tab
键(或使用上下键选择后按 Enter
键):
触发词 |
描述 |
适用场景 |
doc-summary |
方案概要模板 |
记录需求的核心实现思路和上下文 |
doc-decision |
决策点注释 |
记录关键技术选型和设计决策 |
doc-testFocus |
测试重点注释 |
标注需要重点测试的功能场景 |
doc-fix |
BUG修复注释 |
记录问题修复原因和方案 |
doc-feature |
特性点注释 |
标记新功能的实现要点 |
注释模板插入后,可通过 Tab
键在各字段间快速切换,填写相应内容。所有文档注释都遵循统一的结构,让团队成员能够轻松找到所需信息。
2. 在侧边栏查看和管理文档
- 点击 VS Code 侧边栏中的 CoDoc 图标
- 在树视图中可以看到项目中所有的文档注释
- 使用顶部的工具栏按钮:
- ↻扫描文档注释 - 更新最新的文档注释
- ᯤ筛选文档 - 按条件筛选显示的文档
- ⤴︎导出文档注释 - 导出选中的文档注释
3. 导出文档注释
- 在项目注释扫描完成以后,点击工具栏「⤴︎导出文档注释」
- 在筛选界面中选择需要导出的:
- 需求 ID / BUG ID(多选)
- 注释类型(多选)
- 插件会自动生成完整的 Markdown 格式变更文档
📝 注释模板详解
方案概要模板
在需求相关的核心代码处填写,说明整体实现思路,每个需求仅需一个概要文档。
// 示例
// @summary(JIRA-123) 购物车本地缓存方案
// - context: 购物车数据需要在多个页面共享,且需要离线访问
// - why: 为了提升用户体验,减少网络请求
// - how: 使用 localStorage 缓存购物车数据,定时同步到服务器
// - domain: cart,storage
// @endSummary
决策点注释模板
记录方案实施中的关键技术决策和设计考量。
// 示例
// @decision 选择使用 RESTful API 而非 gRPC
// - req: JIRA-123
// - why: 因为 RESTful API 更易于开发和快速迭代,无需频繁更新客户端
// - how: 使用框架集成的 HTTP Client
// - risk: 暂无
// - domain: api,network
// @endDecision
测试重点模板
标记需要重点测试的功能点或场景,便于测试团队定向验证。
// 示例
// @testFocus 验证用户登录逻辑处理
// - req: JIRA-101, JIRA-102
// - usecase: 验证用户多次输入错误密码时的账户锁定机制
// - businessRule:
// - 用户连续输入错误密码超过 5 次,账户将被锁定 30 分钟
// - 锁定期间,用户无法登录
// - 登录成功后,锁定时间将重置
// - checkMethod: 使用自动化测试模拟连续登录失败场景
// - risk: 锁定机制可能影响合法用户的登录体验
// - domain: user,security
// @endTestFocus
BUG修复注释模板
记录BUG修复的原因、方案和影响范围。
// 示例
// @fix(BUG-456) 修复订单金额计算错误
// - why: 当订单包含多种折扣类型时,计算顺序错误导致最终价格不准确
// - how: 修改折扣计算顺序,先应用固定金额折扣,再应用百分比折扣
// - risk: 可能影响历史订单数据的一致性
// - req: JIRA-789, JIRA-321
// - domain: order,payment
// @endFix
特性点注释模板
标记重要功能点或特性实现。
// 示例
// @feature 用户登录状态持久化
// - req: JIRA-101
// - 实现方式: 使用 JWT 令牌存储在 localStorage 中
// - 安全考量: 添加令牌失效机制,最长保持登录状态 7 天
// @endFeature
🎨 注释高亮显示
为提高代码可读性,本扩展集成了注释高亮功能,不同类型的注释标记使用不同颜色显示:
注释类型 |
颜色 |
含义 |
@summary |
蓝色 (#3498DB) |
方案概述,冷静和信息性 |
@decision |
橙色 (#F39C12) |
决策点,需要引起注意 |
@testFocus |
绿色 (#98C379) |
测试重点,与测试成功相关联 |
@fix |
红色 (#FF2D00) |
问题修复,警示性强 |
@feature |
紫色 (#CE91C8) |
新功能或特性点,体现创新 |
注释高亮功能依赖 Better Comments Next 扩展,插件会自动检查并应用高亮配置。
⚙️ 扩展设置
在 VS Code 设置中可以自定义以下选项:
// TODO
🔧 支持的编程语言
- JavaScript / TypeScript / React
- Go
- PHP
- Java
- ...
📈 开发路线图
- [ ] 支持项目级统一配置、解析业务领域ID
- [ ] 支持注释块内的内容提示和自动补全
- [ ] 统计各类文档覆盖率和质量指标
- [ ] 集成Jira,联动需求/缺陷信息
🔌 安装与依赖
- 在 VS Code 扩展市场中搜索并安装
CoDoc
- 插件会自动检查并提示安装依赖扩展 Better Comments Next
- 重启 VS Code 后,CoDoc 将自动激活并准备就绪