1. 被注释淹没的日常为什么我最终留下了 Show Comment写 Java 的人大概都有过这种体验接手一个三四年前的项目打开一个 Service 类方法体上面压着七八行注释有 Javadoc、有行内说明、有被注释掉的旧代码、还有// TODO和// FIXME混在一起。你想快速看清这个方法到底干了什么结果眼睛先被注释墙挡了一遍。更麻烦的是有些注释和代码早就对不上了——注释说返回用户列表实际代码返回的是分页对象你还得逐行核对。我日常主力是 IntelliJ IDEA社区版和旗舰版都用过。IDEA 本身对注释的处理其实已经不错了比如可以折叠 Javadoc、可以高亮 TODO。但有个细节一直让我不太舒服注释和代码在视觉上是平权的它们用同样的字号、同样的行高只是颜色淡一点。当注释量大的时候代码反而成了配角。我试过手动折叠、试过调低注释颜色的对比度但都是治标不治本。后来在插件市场里翻到Show Comment这个插件装上用了一周就离不开了。它的核心逻辑非常朴素把注释从代码流里抽出来用更轻量的方式呈现让你在需要的时候一眼看到不需要的时候完全不占地方。它主要面向 Java 的 Javadoc 和行注释对 JSON 这类配置文件里的注释也有一定支持。说白了它解决的不是注释有没有用的问题而是注释怎么展示才不碍事的问题。这篇文章适合几类人看一是每天在 IDEA 里泡着、被注释干扰阅读效率的 Java 开发者二是团队里负责代码规范、想让注释真正发挥文档作用的技术负责人三是刚接触 IDEA、还在摸索插件生态的新手。我会从它到底改变了什么、怎么装怎么配、实际用下来哪些场景最爽、哪些坑要避开这几个角度把这一周的实测经验完整摊开讲。2. Show Comment 到底改了什么从注释墙到按需展开2.1 传统注释展示的三个痛点在讲插件之前得先把问题说清楚不然你感受不到它到底省了什么。第一个痛点是空间占用。一个规范的 Javadoc 通常包含param、return、throws、author、since等标签一个方法光注释就占十几行。当你在一个类里连续看五六个方法时注释占的垂直空间可能比代码还多。IDEA 虽然支持折叠但折叠后只剩一行/** ... */你又不知道里面写了什么得反复展开收起。第二个痛点是信息密度低。注释里真正有用的往往就一两句比如这个方法会触发异步刷新剩下的都是模板化的标签。但传统展示方式把所有内容一视同仁地铺开你每次都要在噪音里找信号。第三个痛点是注释与代码的割裂。注释在上、代码在下中间隔着几行视线要来回跳。尤其是方法签名很长的时候你看到注释、再往下找方法名中间还要跨过参数列表阅读节奏被打断。2.2 Show Comment 的呈现思路Show Comment 的做法是把注释内容以更紧凑、更贴近代码的方式重新组织。它不会删除注释也不会改变源文件只是在编辑器渲染层面做了一层视图转换。具体来说它会把 Javadoc 里的关键信息提取出来用更小的视觉权重展示同时保留展开查看完整注释的能力。我实测下来它最直观的改变有三个注释行高被压缩同样的屏幕能多看 30% 到 50% 的代码Javadoc 标签被结构化处理param和return不再是一行行平铺而是以更紧凑的块呈现行内注释//和/* */的展示更克制不会在代码右侧形成一条长长的注释尾巴。这里要说明一点插件的具体渲染行为会随版本变化我用的这个版本对 Javadoc 的支持最成熟对 JSON 注释的支持属于能用但别期待太多。JSON 本身标准里是不允许注释的但很多工具链比如某些配置解析器支持//和/* */Show Comment 对这类文件也能做一定程度的注释折叠不过效果不如 Java 文件明显。2.3 它和 IDEA 自带折叠的区别很多人会问IDEA 自带折叠不就行了吗我一开始也这么想但实际对比后发现差别不小。对比维度IDEA 自带折叠Show Comment折叠后可见信息只剩一行占位符保留注释摘要或关键标签展开操作需要点击或快捷键可配置为悬停或按需展开Javadoc 标签处理整体折叠不区分结构化提取重点突出行内注释基本不处理有专门的紧凑展示对代码的侵入无无纯视图层关键差异在于折叠后的信息保留。IDEA 折叠后你什么也看不到必须展开Show Comment 让你在折叠状态下也能瞥见注释的核心内容这就把注释作为文档和注释不占空间这两个矛盾的需求同时满足了。提示插件只改变编辑器的显示方式不会修改你的源文件也不会影响 Git 提交内容。这一点可以放心团队协作时不会因为有人装了插件就导致代码 diff 变化。3. 装之前先想清楚环境、版本与安装路径3.1 确认你的 IDEA 版本和发行版Show Comment 是 IntelliJ IDEA 的插件理论上社区版Community和旗舰版Ultimate都能装。但这里有个细节部分插件会依赖旗舰版独有的功能比如某些对 Spring、数据库工具的支持。Show Comment 本身是纯编辑器层面的增强我实测在社区版上运行正常没有出现功能缺失。版本方面IDEA 的插件市场会标注兼容的 IDE 版本范围。如果你用的是比较老的版本比如 2020 以前的可能会遇到插件不兼容或者功能受限的情况。我的建议是尽量用近两年的稳定版插件作者通常会优先适配新版本。如果你还在用很老的版本先升级 IDE 再考虑装插件不然排查兼容性问题会浪费很多时间。3.2 两种安装方式的实际体验安装插件有两条路我都试过各有适用场景。方式一IDEA 内置插件市场。路径是File - Settings - Plugins - Marketplace搜索 Show Comment。这是最省事的方式点 Install 然后重启 IDE 就行。优点是版本自动匹配、更新方便缺点是如果网络环境不稳定市场加载可能会慢或者搜不到。方式二离线安装。从插件市场网页下载对应版本的.jar或.zip包然后在Plugins页面点齿轮图标选Install Plugin from Disk。这种方式适合内网环境或者市场访问不畅的情况。要注意的是离线包必须和你的 IDE 版本匹配下错了版本装上去会报兼容性错误甚至导致 IDE 启动异常。我个人的习惯是优先用内置市场因为更新提醒更及时。离线安装只在帮同事配内网机器时用过装完记得核对一下插件版本号别装了个两年前的旧版。3.3 安装后必须做的一步重启与索引装完插件后 IDEA 会提示重启这一步别跳过。重启后IDEA 会重新建立索引大项目可能要等几分钟。在索引没完成之前插件的渲染效果可能不正常比如注释没被压缩、或者显示错乱。我一开始没注意以为插件坏了等索引跑完才发现一切正常。注意如果你装完插件后发现编辑器行为异常比如代码高亮错乱、折叠失效先别急着卸载。等索引跑完或者手动触发File - Invalidate Caches / Restart大部分问题都能解决。4. 配置项逐个拆哪些值得开哪些建议关4.1 找到配置入口装好插件后配置项通常在两个地方一是Settings - Other Settings - Show Comment不同版本路径可能略有差异二是编辑器右键菜单里可能有快捷开关。我建议先去 Settings 里把全局配置过一遍再根据具体文件类型做微调。4.2 核心配置项的实际效果我把用下来觉得最值得关注的几个配置项列出来附上我的实际设置和理由。注释折叠粒度。这个选项决定注释被压缩到什么程度。有仅折叠 Javadoc折叠所有注释按注释长度自动折叠等模式。我选的是折叠所有注释因为我的项目里行内注释也很多统一处理更省心。如果你只关心 Javadoc选第一个就行行内注释保持原样。Javadoc 标签展示方式。可以选完整展示仅展示描述结构化展示。我推荐结构化展示它会把param、return这些标签用更紧凑的格式排列比完整展示省空间又比仅展示描述信息全。悬停展开。开启后鼠标悬停在折叠的注释上会自动展开完整内容。这个功能很实用但有个小坑如果你的鼠标经常在代码上划过可能会频繁触发展开反而干扰阅读。我的做法是开启悬停展开但把触发延迟调高一点比如 500 毫秒这样只有真正停下来看的时候才会展开。行内注释处理。对于//开头的行内注释可以选保持原样压缩到行尾折叠隐藏。我选的是压缩到行尾这样注释还在但不会单独占一行。不过要注意如果注释很长压缩到行尾可能会导致代码行超出屏幕宽度这时候要么换行要么隐藏得根据你的屏幕宽度权衡。4.3 按文件类型差异化配置Show Comment 支持针对不同文件类型设置不同规则。我的配置是这样的Java 文件全量开启Javadoc 结构化展示行内注释压缩到行尾JSON 文件只开启注释折叠不做结构化处理因为 JSON 注释本来就不规范其他文件默认关闭避免干扰。这样配置的好处是我在写 Java 时享受完整的注释优化切到 JSON 配置文件时也不会因为插件行为不一致而困惑。提示配置改完后建议打开一个注释密集的类文件实际看一眼效果别只看设置页面的预览。有些选项的组合效果和单独看说明不太一样实测最靠谱。5. 真实项目里的四个高频场景5.1 阅读遗留代码快速判断方法职责接手老项目时我最常做的事就是快速扫一遍类里的方法判断哪些需要细看、哪些可以跳过。以前的做法是逐个展开 Javadoc看return和描述。现在有了 Show Comment折叠状态下就能看到注释摘要扫一眼就知道这个方法大概是干什么的。举个例子一个订单服务类里有createOrder、cancelOrder、queryOrder、syncOrderStatus等方法。折叠后每个方法上方只显示一行摘要我能在几秒内定位到syncOrderStatus的注释写着定时任务调用勿手动触发这种关键信息如果被埋在完整 Javadoc 里很容易漏看。5.2 写新代码让注释真正被看见有意思的是这个插件不仅改善了读也间接改善了写。因为注释被压缩展示了我反而更愿意写注释了——以前觉得写 Javadoc 会让代码变长、看着累现在注释不占地方写起来没负担。而且团队里有个正向效应当注释以更清晰的方式呈现时注释和代码不一致的问题更容易被发现。以前注释被折叠或淹没没人注意现在注释摘要就在方法上方如果写的是返回用户列表但方法名是getUserPage一眼就能看出不对劲。5.3 代码评审减少注释噪音干扰做 Code Review 时diff 里经常混着大量注释变更。Show Comment 虽然不直接改变 diff 视图但它让我在 IDE 里看代码时更聚焦于逻辑本身。评审时我会先把注释折叠起来专注看代码结构然后再展开注释核对文档是否更新。这个先代码后注释的顺序比一上来就被注释带着走要客观得多。5.4 JSON 配置排查注释折叠的意外用处前面说过 JSON 注释支持有限但有个场景它帮了我大忙。我们有些配置文件用 JSON 格式里面用//写了大量环境说明和字段解释。这些注释在排查配置问题时很有用但平时又很碍眼。Show Comment 能把它们折叠起来需要的时候再展开比手动删注释或者用外部文档记录要方便。不过要提醒一句JSON 标准不支持注释如果你的配置文件会被严格的 JSON 解析器读取注释可能导致解析失败。Show Comment 只是显示层面的处理不会帮你把注释合法化。所以用之前先确认你的解析器是否容忍注释。6. 踩过的坑与排查链路6.1 装完没效果先查索引和文件类型我第一次装完插件打开一个 Java 文件发现注释根本没变化当时以为装了个假插件。排查过程是这样的先确认插件已启用Settings - Plugins - Installed里能看到且勾选检查当前文件类型是否在插件的生效范围内有些插件默认只对特定语言生效等待索引完成或者手动Invalidate Caches / Restart检查配置项是否被误关比如全局开关没打开。最后发现是索引没跑完。等了几分钟后一切正常。这个坑很典型IDEA 插件装完后如果行为异常第一反应应该是等索引而不是怀疑插件本身。6.2 注释显示错乱版本兼容性问题有一次帮同事装他用的 IDE 版本比较老装完最新版插件后注释显示错乱部分中文注释变成乱码。排查下来是插件版本和 IDE 版本不匹配。解决办法是去插件市场找历史版本下载一个兼容他 IDE 版本的旧版插件。这里有个经验插件不是越新越好要和你的 IDE 版本匹配。尤其是团队里 IDE 版本不统一的时候最好约定一个大家都兼容的插件版本避免有人显示正常有人显示异常。6.3 悬停展开太灵敏调整触发延迟前面提过悬停展开的坑。我一开始开着默认延迟结果鼠标在代码区移动时注释频繁弹出非常干扰。后来把延迟调到 500 毫秒以上体验就好多了。如果你也觉得悬停展开烦可以先关掉需要时手动展开或者调高延迟。6.4 和格式化插件的冲突我同时装了代码格式化相关的插件有次发现保存时注释格式被改来改去。排查后发现是两个插件对注释的处理顺序有冲突。解决办法是调整插件优先级或者把 Show Comment 设为仅显示不修改确保它不参与任何格式化动作。注意Show Comment 本身是视图层插件正常不会修改源文件。但如果你同时装了其他会操作注释的插件建议先确认各自的职责边界避免互相打架。7. 和其他 IDEA 效率插件的搭配思路7.1 与代码折叠类插件的分工IDEA 生态里做代码折叠的插件不少有的专注折叠方法、有的专注折叠 import。Show Comment 专注注释两者不冲突。我的做法是代码结构折叠交给专门插件注释展示交给 Show Comment各管一摊互不干扰。7.2 与 TODO 管理插件的配合很多团队用 TODO 管理插件来追踪// TODO和// FIXME。Show Comment 会把这类注释也纳入折叠范围可能导致 TODO 不那么显眼。我的处理方式是在 Show Comment 配置里把TODO、FIXME这类标记排除在折叠之外让它们保持高亮这样既不占空间又不会漏掉。7.3 与主题和字体设置的协调注释压缩后字号和颜色的搭配会更敏感。我用的是深色主题注释颜色调得比较淡。压缩后如果颜色太淡反而看不清摘要。建议装完插件后重新调一下注释颜色保证折叠状态下的摘要清晰可读展开后的完整注释可以淡一些。8. 一些不那么显然的使用心得8.1 别指望它解决注释质量问题Show Comment 解决的是展示问题不是内容问题。如果注释本身写得乱七八糟、和代码对不上插件只会让这些烂注释更整齐地呈现出来不会让它们变好。所以它是个放大器好注释更好用烂注释更显眼。从这个角度看它反而能倒逼团队提升注释质量。8.2 团队推广要循序渐进如果你想在团队里推广这个插件别一上来就要求所有人装。我的做法是先自己在几个项目里用收集实际效果然后在团队分享会上演示装之前 vs 装之后的对比。等有人主动问你那个注释怎么这么清爽的时候再推荐接受度会高很多。8.3 定期检查配置是否被重置IDEA 升级或者插件更新后配置有时会被重置。我有次升级 IDE 后发现注释又变回原样了检查发现是插件配置被恢复默认。建议在 IDE 大版本升级后花两分钟检查一下插件配置避免用着用着效果没了还不知道原因。8.4 对性能的影响可以忽略我特意在几个大项目里观察过开启 Show Comment 后编辑器的滚动、输入、跳转都没有明显卡顿。它做的是视图层渲染不涉及复杂的代码分析所以性能开销很小。如果你的机器本身配置不高也不用担心它成为瓶颈。9. 关于注释展示这件事我的最终选择用了一周多Show Comment 已经成了我 IDEA 必装插件清单里的一员。它没有惊天动地的功能就是把一件小事——注释怎么显示——做到了位。但恰恰是这种小事每天要重复几百次累积起来的效率提升很可观。我现在的工作流是这样的打开一个类注释默认折叠扫一眼摘要定位到目标方法需要细节时悬停展开看完继续折叠。整个过程行云流水不再有注释墙挡路的感觉。写代码时也因为注释不占地方更愿意随手补上说明。如果你也在被注释干扰阅读效率我的建议是先装上看一周重点体验折叠状态下的摘要和悬停展开这两个功能。如果一周后你发现自己已经习惯了这种阅读节奏那就留下它如果觉得多余卸载也不会有任何副作用。工具这东西适合自己的才是最好的。最后分享一个小技巧装完插件后找项目里注释最密集的那个类分别截一张装之前和装之后的图。对比一下你会直观地看到它到底省了多少视觉空间。这个对比图也是我在团队里推广时最有效的证据。