注释标签治理：不只使用 TODO

很多同学在 Java 项目里写待办注释时，几乎只会用一种写法：

// TODO: 这里后面要重构

时间一长，项目里到处都是 TODO。问题比较严重的 bug、临时 HACK、需要重点 Review 的地方，全都和普通“以后再说”的 TODO 混在一起，最后根本分不清轻重缓急。

其实，IDE 本身就支持很多“类似 TODO 的任务标签”。如果把这些标签用起来，再配合 IntelliJ IDEA 或 Eclipse 的任务面板，代码里的提醒信息会比单纯堆 TODO 清晰得多。

---

一、常见的任务型注释标签有哪些？

除了最常见的 TODO 之外，在 Java 项目里还经常会用到这些标签：

• FIXME：这里有已知问题，需要修复
• XXX：实现看起来可疑，建议重点关注
• HACK：临时方案、权宜之计，后面应该替换掉
• NOTE / INFO：重要说明，不一定代表后续要改代码
• BUG：明确标记这是个缺陷点
• OPTIMIZE：这里可以做优化，比如性能、结构、可维护性
• REVIEW：这里建议代码评审时重点看

这些标签本质上都只是注释里的关键字。IDE 会不会把它们识别成“任务”，取决于你有没有在配置里把它们注册进去。

---

二、为什么很多 IDE 默认只识别 TODO / FIXME？

很多人会遇到一个现象：

• 代码里写了 HACK
• 写了 OPTIMIZE
• 写了 REVIEW

但在 TODO 面板里却完全看不到。

原因很简单：

IDE 默认只会根据你配置过的 Task / TODO Patterns 去扫描注释。

也就是说，只有被配置成“任务标签”的关键字，才会被 IDE 收集到任务面板里。

IntelliJ IDEA

路径在：

Settings / Preferences → Editor → TODO

默认通常只会包含：

• TODO
• 有时带上 FIXME

Eclipse

路径在：

Preferences → Java → Compiler → Task Tags

默认一般会有：

• TODO
• FIXME
• XXX

没配置进去的标签，IDE 就只会把它们当普通注释处理。

---

三、在 IntelliJ IDEA 里让更多标签生效

如果你主要用 IDEA，建议优先把团队真正会用到的任务标签配起来。

1. 打开 TODO 配置

路径是：

Settings / Preferences → Editor → TODO

这里会看到一个 Patterns 列表，里面就是当前 IDEA 会识别的任务模式。

2. 新增你需要的标签

可以按这种方式增加：

• \bHACK\b.*
• \bXXX\b.*
• \bOPTIMIZE\b.*
• \bREVIEW\b.*

这里要注意两点：

第一，IDEA 用的是正则表达式，不是简单文本匹配。

第二，\\bTAG\\b.* 这种模式很实用：

• \b 表示单词边界，避免误匹配
• .* 表示把这行后面的描述也一起抓进任务面板

配置完成后，IDEA 会重新扫描这些标签，你就能在 TODO Tool Window 里统一看到它们。

---

四、在 Eclipse 里怎么配 Task Tags？

如果你用 Eclipse，思路其实一样，只是入口位置不同。

1. 找到 Task Tags 设置

路径：

Preferences → Java → Compiler → Task Tags

这里会列出当前被识别的任务标签。

2. 根据团队约定做增删

比如你可以增加：

• HACK
• OPTIMIZE
• REVIEW

也可以删除团队里几乎没人使用的标签，避免任务视图太杂。

Eclipse 还有一个比较实用的地方，就是可以给不同标签配置优先级：

• FIXME / BUG：High
• TODO：Normal
• OPTIMIZE：Low

这样任务视图不只是分类更清楚，连紧急程度也更容易区分。

---

五、团队实践里，标签不要贪多

很多团队一开始接触这类标签时，会有一个常见误区：

既然能自定义，那就把所有可能想到的关键词都加进去。

结果很快就会发现两个问题：

• 标签太多，搜索和筛选成本反而更高
• 不同人理解不同，同一个标签的语义越来越混乱

从实践角度，我更建议：

核心标签控制在 2 到 4 个，够用就好。

比如一个比较实用的组合可以是：

• TODO：待完成的工作、重构、补测试、补文档
• FIXME：已知缺陷，必须修
• OPTIMIZE：未来可优化的地方
• REVIEW：建议重点评审的代码

这样既有分层，又不会复杂到没人记得住。

---

六、进一步升级：和 Issue 编号结合起来

如果团队已经有工单系统或 Issue 系统，任务标签还可以进一步规范化。

比如：

// FIXME(#1234): 这里并发场景下有问题
// TODO(#5678): 这里后面替换成统一鉴权组件

这种写法有两个额外好处：

• 任务可以追溯到具体工单
• 后期清理时更容易判断是否已经处理完

从代码治理角度，这比单纯写一个“TODO: 后面再改”有价值太多。

---

七、几个很容易踩的坑

1. 只看高亮，不看任务面板

编辑器里的颜色高亮有时会受主题、Inspection、插件等影响。

真正稳定的依据，还是 TODO / Tasks 面板里有没有被识别出来。

2. 正则写得太宽，误匹配一大片

如果任务模式写得过于宽泛，就可能把根本不想识别的内容也扫进去。

所以优先推荐这类清晰模式：

\bTODO\b.*
\bFIXME\b.*
\bHACK\b.*

3. 团队没有统一约定

如果每个人都发明一套标签体系，最后的结果一定是混乱。

所以最好的做法是：

• 团队统一约定允许使用哪些标签
• 明确每个标签的语义
• 约定是否要带 Issue 编号

这样这些注释才不只是“个人提醒”，而能成为团队协作的一部分。

---

八、最后总结

如果只记住一件事，那就是：

项目里的任务型注释，不应该只有 TODO 一种。

更合理的做法是：

• 用不同标签区分待办、缺陷、临时方案、优化点、评审点
• 在 IDEA 或 Eclipse 里把这些标签配置进任务系统
• 控制标签数量，避免泛滥
• 最好再和 Issue 编号结合，提高可追踪性

这样一来，注释就不再只是“顺手写一句提醒”，而是能被 IDE 收集、被团队识别、被后续治理真正利用起来的结构化信息。