1. 为什么你的注释总是一片灰Better Comments 到底解决了什么写代码的时候注释是绕不开的东西。可大多数人写出来的注释在编辑器里就是一片灰扑扑的斜杠加文字跟代码本身混在一起扫一眼根本分不清哪句是提醒、哪句是待办、哪句是暂时不想删的调试代码。时间一长注释越堆越多反而成了阅读负担。Better Comments 这个 VSCode 插件干的事情很纯粹它把注释按你定义的标记符号分类然后给每一类配上不同的颜色、背景色甚至删除线。你写// TODO: 补上边界判断TODO 会变成醒目的橙色你写// ! 这里不能动感叹号后面的内容会变成红色警告你写// ? 这个逻辑待确认问号会变成蓝色疑问。一眼扫过去代码里的重点、风险点、待办项自动跳出来。它适合谁适合每天在 VSCode 里写代码、想让注释真正发挥作用的开发者。不管你是写 JavaScript、Python、Go 还是 Rust只要 VSCode 能识别注释语法Better Comments 就能生效。它不改变代码逻辑只改变注释的呈现方式所以没有任何运行时风险装上就能用。我试过在几个中型项目里用它最直观的感受是以前 review 代码要逐行读注释现在扫颜色就知道哪里需要重点关注。尤其是团队协作时TODO 和警告类注释的视觉区分能省下不少沟通成本。这一篇会从安装讲到 settings.json 配置再到自定义标记规则和逐项验证最后把常见的报错和排查也带上。你跟着做十分钟内就能让注释变得好看又好用。2. 安装 Better Comments 与 TaoToken 前置准备2.1 在 VSCode 里装插件打开 VSCode点左侧活动栏的扩展图标四个方块那个在搜索框里输入Better Comments。排在第一位的通常是 Aaron Bond 发布的那个图标是一个彩色注释气泡。点进去点 Install几秒钟就装好了。装完之后不需要重启VSCode 会自动激活。你随便打开一个代码文件写一行// TODO: 测试如果 TODO 变成橙色说明插件已经生效。如果没变色先别急后面第五节会讲排查。2.2 为什么这里要提 TaoTokenBetter Comments 本身是个纯本地插件不依赖任何网络服务。但如果你在写代码的过程中需要调用大模型来生成注释、解释代码或者做代码补全那就需要一个稳定的 API 入口。TaoToken 提供的就是这个入口它的 API 地址是https://taotoken.net/api兼容 OpenAI 风格的请求格式你可以在 VSCode 的 AI 编程插件里直接配置。具体来说如果你用 Cline、Continue 或者 Claude Code 这类工具把 Base URL 填成https://taotoken.net/api再配上在 TaoToken 控制台生成的 API Key就能在写代码的同时让模型帮你生成带标记的注释。比如你选中一段函数让模型生成// TODO:和// !标记的注释模型输出后 Better Comments 会自动上色整个流程是打通的。TaoToken 的 API Key 在控制台创建地址是https://taotoken.net/api-keys。创建的时候给它起个名字比如vscode-comment-helper方便后面管理。Key 只显示一次复制下来存好。如果你还没决定用哪个模型可以先在模型对话页面试试效果地址是https://taotoken.net/models。选一个你顺手的模型测试一下让它生成带标记的注释看看输出格式是否符合你的预期。2.3 前置准备清单在继续之前确认这几件事VSCode 已经安装版本不要太老建议 1.70 以上。Better Comments 插件已安装并激活。如果你要用 AI 生成注释TaoToken 的 API Key 已经创建好Base URL 记牢https://taotoken.net/api。你有一个可以随便改的测试文件比如test.js或test.py用来验证颜色效果。这些准备好之后就可以进入配置环节了。3. 可复制的 settings.json 配置与自定义标记规则3.1 打开 settings.jsonBetter Comments 的所有配置都写在 VSCode 的settings.json里。打开方式有两种第一种按Ctrl Shift PMac 是Cmd Shift P输入Open Settings (JSON)回车。第二种点左下角齿轮图标选 Settings然后点右上角那个带箭头的文件图标切换到 JSON 视图。打开之后你会看到一个 JSON 对象。如果之前没配过 Better Comments里面不会有better-comments.tags这个键。你需要手动加上。3.2 默认五类标记的配置片段下面这段是 Better Comments 的默认标记配置你可以直接复制到settings.json里。注意如果你已经有其他配置把它放在最外层大括号内跟其他键平级记得加逗号。better-comments.tags: [ { tag: !, color: #FF2D00, 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 } ]这段配置定义了五类标记!红色用于警告比如// ! 不要删这行。?蓝色用于疑问比如// ? 这里为什么要加锁。//深灰色加删除线用于注释掉的代码比如// // oldFunction()。todo橙色用于待办比如// TODO: 补测试。*绿色用于高亮重点比如// * 核心逻辑。注意tag的匹配是不区分大小写的所以你写TODO、Todo、todo都能命中。3.3 自定义标记加一个标记默认五类不够用怎么办直接加。比如我想加一个标记用来标注“需要 review 的地方”颜色用紫色#9B59B6背景色给一个淡淡的紫#2C1B3D让它更显眼。在better-comments.tags数组里追加一个对象{ tag: , color: #9B59B6, strikethrough: false, backgroundColor: #2C1B3D }加完之后整个数组变成六个对象。保存settings.jsonVSCode 会立即生效不需要重启。然后你在代码里写// 这里需要 review后面的文字就会变成紫色背景带淡紫。效果比默认的灰色注释强很多。3.4 配置项参数说明每个标记对象支持四个字段字段类型说明tagstring触发标记的符号或单词比如!、?、todocolorstring文字颜色十六进制色值比如#FF2D00strikethroughboolean是否加删除线true 或 falsebackgroundColorstring背景色transparent表示透明也可以填色值color和backgroundColor都支持标准的十六进制颜色。如果你不确定用什么颜色可以去网上搜“hex color picker”选一个顺眼的。3.5 一个完整的 settings.json 示例如果你想让配置更完整可以把下面这段整体复制进去。它包含了默认五类加自定义标记还顺带配了一个 TaoToken 的 API 地址方便你在 AI 插件里用。{ better-comments.tags: [ { tag: !, color: #FF2D00, 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: , color: #9B59B6, strikethrough: false, backgroundColor: #2C1B3D } ], better-comments.multilineComments: true, better-comments.highlightPlainText: false }better-comments.multilineComments设为 true 时多行注释里的标记也会生效。better-comments.highlightPlainText设为 false 表示不在纯文本文件里高亮避免干扰。保存之后配置就生效了。4. 逐项验证注释变色、TODO/警告/疑问标签是否生效配置写完接下来要验证。别跳过这一步因为颜色不生效的原因往往藏在细节里。4.1 验证!警告标记新建一个文件test.js写一行// ! 这行代码不能删删了会崩保存。如果!后面的文字变成红色#FF2D00说明警告标记生效。如果没变色检查settings.json里tag是不是!以及有没有拼写错误。4.2 验证?疑问标记再写一行// ? 这里为什么要用递归改成循环会不会更好保存。问号后面的文字应该变成蓝色#3498DB。如果没变检查tag是不是?注意问号是英文半角不要写成中文问号。4.3 验证todo待办标记写一行// TODO: 补上参数校验保存。TODO 后面的文字应该变成橙色#FF8C00。这里注意tag写的是小写todo但匹配时不区分大小写所以你写TODO、Todo都能命中。4.4 验证*高亮标记写一行// * 核心逻辑改动前先看文档保存。星号后面的文字应该变成绿色#98C379。4.5 验证//删除线标记写一行// // oldFunction() 已废弃保存。第二个//后面的文字应该变成深灰色#474747并且带删除线。这个标记的用途是保留被注释掉的代码但让它视觉上“退后”不干扰阅读。4.6 验证自定义标记写一行// 这里需要 review逻辑可能有问题保存。后面的文字应该变成紫色#9B59B6背景带淡紫#2C1B3D。如果背景色没出来检查backgroundColor是不是写成了background-colorJSON 里必须是驼峰命名。4.7 验证多行注释如果你把better-comments.multilineComments设为 true可以测试多行注释/* * TODO: 重构这个模块 * ! 注意线程安全 * ? 是否需要加缓存 */保存后TODO、感叹号、问号应该分别变色。如果多行注释没生效检查那个配置项是不是 true。4.8 验证 AI 生成注释的联动如果你配了 TaoToken 的 API可以在 Cline 或 Continue 里让模型生成一段带标记的注释。比如选中一个函数输入提示词“给这个函数生成注释用 TODO 标记待办用 ! 标记风险点”。模型输出后Better Comments 会自动上色。TaoToken 的 Base URL 填https://taotoken.net/apiAPI Key 填你在控制台创建的那个。模型 ID 根据你选的模型填比如gpt-4o或claude-3-5-sonnet。配置好之后让模型生成注释看看颜色是否正常。如果模型输出的注释没有变色先检查注释格式是不是// TODO:这种标准写法再检查settings.json里的tag有没有被改错。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth配置和使用过程中最容易卡住的地方往往不是插件本身而是周边环境。下面这几类报错我踩过坑也帮别人排查过整理出来供你对照。5.1 401 报错API Key 无效或没带对如果你在 AI 插件里调用 TaoToken 的 API 时看到401 Unauthorized通常是这几个原因第一API Key 复制错了。TaoToken 的 Key 只在创建时显示一次如果你没存好只能去控制台重新创建一个。创建地址是https://taotoken.net/api-keys。第二请求头里没带 Key。OpenAI 风格的请求需要在 Header 里加Authorization: Bearer 你的Key。如果你用的是 Cline 或 Continue在设置界面填 API Key 的地方填对就行不用手动拼 Header。第三Base URL 写错了。TaoToken 的 API 地址是https://taotoken.net/api注意结尾没有斜杠。有些插件会自动补/v1如果补错了也会 401。你可以在插件的 Base URL 设置里明确填https://taotoken.net/api让它自己去拼路径。排查方法用 curl 直接测一下。curl https://taotoken.net/api/models \ -H Authorization: Bearer 你的Key如果返回模型列表说明 Key 和地址都对。如果返回 401就是 Key 的问题。5.2 local proxy failed本地代理没起来或端口冲突这个报错通常出现在你用了本地代理工具或者插件配置了http://localhost:xxxx作为 Base URL 的时候。Better Comments 本身不涉及网络所以这个错一般是在 AI 插件里出现的。原因一你填的 Base URL 是本地地址但本地服务没启动。比如你之前用 Ollama 或 LM Studio填了http://localhost:11434但服务没开。解决办法是启动本地服务或者把 Base URL 改成 TaoToken 的https://taotoken.net/api。原因二端口被占用。如果你确实在跑本地服务检查端口是不是被别的进程占了。用lsof -i :端口号查一下杀掉冲突进程或者换端口。原因三插件里的代理设置没关。有些插件有独立的代理配置如果你之前配过代理现在不用了记得关掉。VSCode 本身的http.proxy设置也检查一下如果设了代理但代理不可用也会报 local proxy failed。5.3 reading choices模型返回格式不对这个报错通常出现在你调用模型 API 时返回的 JSON 结构跟插件预期的不一样。比如插件期望choices[0].message.content但实际返回的是choices[0].text就会报 reading choices 相关的错。原因一模型 ID 填错了。不同模型的返回格式可能不同。如果你在 TaoToken 里选了某个模型但插件里填的模型 ID 跟实际不匹配就可能出问题。去https://taotoken.net/models确认一下模型 ID填对。原因二API 版本不对。TaoToken 兼容 OpenAI 风格但如果你在插件里选了 Anthropic 格式而实际调用的是 OpenAI 格式的接口返回结构会对不上。检查插件的 API 类型设置选 OpenAI 兼容。原因三请求参数里带了不支持的字段。比如有些模型不支持temperature或max_tokens的某些取值返回错误结构。简化请求参数只保留model、messages、max_tokens试试。5.4 OAuth 报错认证方式选错了如果你在配置 Claude Code 或类似工具时看到 OAuth 相关的报错通常是因为你选了 OAuth 认证但实际应该用 API Key。TaoToken 的接入方式是 API Key不是 OAuth。所以在 Claude Code 的配置里认证方式选 API KeyBase URL 填https://taotoken.net/apiKey 填你创建的那个。如果你用的是 Claude Code 的auth.json里面应该填{ apiKey: 你的Key, baseUrl: https://taotoken.net/api }注意baseUrl不要带/v1让工具自己去拼。如果你填了https://taotoken.net/api/v1有些工具会拼成/v1/v1/chat/completions导致 404 或 OAuth 报错。5.5 注释不变色插件没生效或配置写错回到 Better Comments 本身。如果你按第三节配了settings.json但注释还是灰色按这个顺序排查第一检查settings.json是不是合法的 JSON。多一个逗号、少一个引号都会导致整个配置失效。VSCode 会在 JSON 文件里用红色波浪线标出语法错误仔细看。第二检查better-comments.tags是不是写在了正确的位置。它必须在外层大括号内跟其他配置平级。如果你不小心把它写进了某个子对象里不会生效。第三检查tag的值。比如你写的是tag: todo但代码里写的是// TODOS:多了一个 S匹配不上。标记后面通常跟冒号或空格但tag本身只匹配标记符号。第四检查文件语言模式。Better Comments 依赖 VSCode 的语法高亮。如果你打开的文件没有被识别为代码文件比如右下角显示 Plain Text注释不会变色。点右下角的语言模式改成对应的语言比如 JavaScript、Python。第五检查插件是否被禁用。在扩展面板里搜 Better Comments看它是不是显示 Disabled。如果是点 Enable。5.6 颜色不生效但标记被识别有时候标记被识别了比如 TODO 加粗了但颜色没变。这通常是color值写错了。检查是不是写成了color: FF8C00少了#。十六进制颜色必须以#开头。另外backgroundColor如果填了transparent背景就是透明的。如果你想看到背景色填一个具体的色值比如#2C1B3D。5.7 多行注释不生效如果你写了多行注释但标记没变色检查better-comments.multilineComments是不是 true。默认可能是 false需要手动打开。另外多行注释的标记位置也有讲究。比如/* * TODO: 重构 */星号后面的 TODO 会被识别。但如果你写成/* TODO: 重构 */没有星号有些情况下也能识别但为了稳定建议加上星号。6. 让注释真正好用的几个实操建议配置和验证都走完之后最后聊几个让 Better Comments 真正融入日常开发的建议。第一团队统一标记规范。如果你们团队用 Git 协作建议在项目根目录放一个.vscode/settings.json把better-comments.tags写进去。这样每个人拉下代码后注释颜色是一致的。标记规范可以约定TODO用于待办!用于风险?用于待确认用于需要 review。写进 README 或者 CONTRIBUTING 里新人一看就懂。第二别滥用标记。如果满屏都是红色感叹号警告就失去了意义。我的习惯是!只用在真正不能动的地方TODO只用在确实要补的事情上?只用在逻辑存疑的地方。标记太多等于没有标记。第三结合 AI 生成注释时给模型明确的格式要求。比如在 TaoToken 的模型对话里你可以这样写提示词“给下面的函数生成注释用// TODO:标记待办用// !标记风险用// ?标记疑问每类最多一条。”模型输出后Better Comments 会自动上色你只需要微调。第四定期清理。TODO和?标记容易越积越多。建议每周花十分钟扫一遍能解决的解决解决不了的改成标记提醒自己下次 review 时重点看。第五如果你用 Claude Code 做长期编码可以在auth.json里配好 TaoToken 的 Base URL 和 Key让模型在生成代码时直接带上标记注释。配置片段{ apiKey: 你的Key, baseUrl: https://taotoken.net/api, model: claude-3-5-sonnet }这样模型生成的注释天然带标记Better Comments 直接上色省去手动改的步骤。第六如果你还没决定用哪个模型来辅助写注释可以去https://taotoken.net/models试试不同模型的效果。有些模型对注释格式的理解更准生成的标记更规范。最后Better Comments 的配置不复杂但细节多。把settings.json备份一份换电脑或者重装 VSCode 时直接复制过去省得重新配。注释好看不是目的让代码更好读、更好维护才是。