1. 为什么我会关注 Show Comment 这款小插件写 Java 的人大概都有过这种体验接手一个三四年前的项目打开某个 Service 类方法名是handleData参数是MapString, Object返回值是Result。你盯着屏幕看了三十秒心里只有一个问题——这玩意儿到底传什么进去、吐什么出来如果当初写这个方法的同事在参数上留了一行 Javadoc哪怕只有一句“传入订单号返回用户积分”你也不至于去翻三个调用方才能猜出意图。Show Comment就是冲着这个场景来的。它是 IntelliJ IDEA 生态里一款非常轻量的辅助插件核心能力只有一件事在你阅读代码时把原本藏在 Javadoc 或行内注释里的说明直接展示在变量、参数、方法调用的位置旁边。你不用按住 Ctrl 点进方法定义也不用把鼠标悬停等 tooltip 弹出来注释内容就静静地待在那里像有人提前帮你把重点划好了。这款插件适合谁我觉得有三类人特别值得装。第一类是维护老项目的后端开发代码注释比文档还全但平时根本看不见第二类是读源码学习的人Spring、Netty 这类框架的 Javadoc 写得极其详尽可默认情况下你只能看到方法签名第三类是团队里负责代码评审的人参数含义一目了然评审效率能提升不少。它不改变你的代码不参与编译纯粹是“阅读体验增强”所以几乎没有引入风险。我用了大概半年多从最初抱着试试看的心态到现在已经把它列进了新机器必装插件清单。下面我把这款插件的设计思路、安装配置、实际效果、踩过的坑以及和 JSON、Javadoc 这些常见格式配合使用的细节完整地梳理一遍。2. Show Comment 的核心设计与思路拆解2.1 它到底解决了什么痛点要理解这款插件的价值得先搞清楚 IDEA 默认是怎么处理注释的。在标准配置下Javadoc 注释只会在两种时机出现一是你把鼠标悬停在方法名上等大约 500 毫秒弹出 tooltip二是你按CtrlQ主动查看快速文档。这两种方式都是“按需触发”意味着你在快速浏览代码时注释实际上是隐形的。问题就出在这里。人读代码是线性的、扫视的眼睛从一行跳到下一行很少会为每个方法都停下来悬停一次。结果就是注释写了等于没写。团队里定规范要求“公共方法必须写 Javadoc”大家老老实实写了但真正读代码的时候没人看规范变成了形式主义。Show Comment 的思路很直接既然注释是给人看的那就让它一直可见。它把注释从“隐藏层”提到了“展示层”在编辑器里以浅色、斜体的形式渲染在对应元素旁边。这个设计选择背后有个重要考量——不能干扰代码本身的视觉结构。所以它的默认样式是低对比度的灰色字号和代码一致位置贴着元素右侧你扫代码的时候余光能瞥见但不会喧宾夺主。2.2 为什么选择“内联展示”而不是“侧边栏”市面上处理注释展示的插件不止一款有的走侧边栏路线在编辑器右侧开一个面板列出当前文件所有注释有的走悬浮卡片路线鼠标移到哪就弹哪。Show Comment 选了最“笨”但也最实用的方案——内联。我仔细想过这个取舍。侧边栏方案的问题是视线跳跃成本高你读代码读到第 50 行注释面板里对应的条目可能在第 8 条眼睛要来回扫。悬浮卡片方案的问题是触发时机不可控你想看的时候它不一定弹不想看的时候它挡住代码。内联展示虽然占了一点横向空间但胜在零交互成本——注释就在它该在的地方和代码形成固定的空间对应关系读起来是连贯的。这个设计对宽屏用户特别友好。我自己的显示器是 27 寸 2K编辑器有效宽度大概能放下 120 个字符Show Comment 展示的注释通常只有十几个字完全不会导致换行。如果你用的是笔记本小屏可以在设置里把注释字号调小或者只对方法参数开启对局部变量关闭灵活度是够的。2.3 和 Javadoc、JSON 的配合逻辑这里要单独说一下 Javadoc 和 JSON 这两个关键词因为它们代表了 Show Comment 最典型的两种使用场景。Javadoc 场景是它的主战场。Java 方法的标准注释格式里param描述参数、return描述返回值、throws描述异常这些信息在 Show Comment 开启后会分别展示在对应位置。比如一个方法签名是public User findById(Long id)Javadoc 里写了param id 用户主键那么你在调用这个方法的地方参数id旁边就会显示“用户主键”。这个体验在阅读层层封装的业务代码时特别爽不用一层层点进去看。JSON 场景稍微特殊一点。Java 项目里经常有把 JSON 字符串转成对象、或者从配置文件读 JSON 的逻辑这些地方往往有注释说明字段含义。Show Comment 对字符串字面量旁边的注释也能识别所以当你看到一段 JSON 模板字符串时旁边的注释会告诉你这个字段对应什么业务含义。我做过一个对接第三方接口的项目请求体是一大坨 JSON每个字段的注释都靠 Show Comment 展示调试的时候省了大量翻文档的时间。需要说明的是Show Comment 本身不解析 JSON 结构它只是把注释文本展示出来。真正让 JSON 可读的是你写的注释质量。这一点后面讲实操的时候会展开。3. 安装配置与核心细节实操要点3.1 插件安装的完整流程安装本身没什么难度但有几个细节值得说清楚尤其是对刚接触 IDEA 插件市场的新手。打开 IDEA从菜单栏进入File→SettingsmacOS 是IntelliJ IDEA→Preferences在左侧找到Plugins。在顶部搜索框输入Show Comment注意别输错成Show Comments或者Comment搜索结果里会有好几个相似名字的插件。认准作者和下载量通常排在第一位的那个就是。点击Install装完后 IDEA 会提示重启。这里有个小坑如果你装插件的时候项目正在编译或者有未保存的改动重启前一定要先保存。我遇到过一次重启后未保存的代码丢了的情况虽然 IDEA 有本地历史能找回但折腾一圈很烦。重启之后插件默认是开启状态。你打开任意一个带 Javadoc 的 Java 文件应该就能看到效果了。如果没看到先别急着怀疑插件没装好往下看配置部分。提示IDEA 社区版和旗舰版都支持这款插件版本兼容性做得不错。但如果你用的是很老的 IDEA 版本比如 2019 以前的建议先去插件页面确认一下兼容范围避免装了用不了。3.2 关键配置项逐个拆解装好之后真正的功夫在配置上。进入Settings→Other Settings→Show Comment你会看到一组选项。我按重要性排序讲。第一个是展示范围。插件允许你分别控制方法参数、局部变量、字段、方法返回值这几类元素的注释展示。我的建议是方法参数和字段全开局部变量看情况。局部变量注释展示有时候会显得很乱因为局部变量的注释往往很短比如// 临时变量展示出来意义不大。但如果你在做一个算法密集的项目局部变量的注释说明了中间计算结果的物理含义那就值得开。第二个是注释来源。可以选择只展示 Javadoc、只展示行内注释//这种、或者两者都展示。我一般选两者都展示因为实际项目里两种注释都有Javadoc 描述接口契约行内注释解释实现细节互补关系。第三个是展示样式。可以调字号、颜色、是否斜体、是否加背景色。默认的浅灰色斜体我觉得就挺好但如果你用的是浅色主题灰色可能对比度不够可以调深一点。深色主题下默认样式反而更清楚。这里有个经验颜色不要选和代码关键字相近的比如别选蓝色否则public、class这些关键字和注释混在一起视觉上会乱。第四个是最大展示长度。注释太长的话全部展示会占满屏幕。插件允许你设置一个字符上限超过部分用省略号代替。我设的是 50 个字符基本能覆盖大部分注释特别长的可以悬停看完整版。配置改完之后不需要重启直接生效。你可以打开一个文件实时调整找到最舒服的样式。3.3 注释书写的规范建议这一点插件文档里不会重点讲但我觉得比插件本身还重要。Show Comment 的效果上限取决于你注释写得好不好。我见过很多项目的 Javadoc 是这么写的/** * 获取用户 * param id id * return 用户 */ public User getUser(Long id) { ... }这种注释展示出来等于没展示因为param id id没有提供任何新信息。好的注释应该是/** * 根据主键查询用户基本信息不包含订单和积分数据 * param id 用户主键对应 t_user 表的 id 字段不可为 null * return 用户实体查不到时返回 null 而非抛异常 */ public User getUser(Long id) { ... }展示出来之后调用方一眼就知道这个方法只查基本信息、id 不能传空、查不到返回 null。这三个信息都是调用时容易踩坑的点。我的建议是如果你打算用 Show Comment就顺手把项目里的关键方法注释按这个标准过一遍。不用全改先把最常被调用的 Service 层方法改了收益最明显。4. 实操过程与典型场景完整演示4.1 场景一阅读第三方框架源码拿 Spring 的BeanFactory接口举例。这个接口里有个方法Object getBean(String name) throws BeansException;默认情况下你只能看到这一行签名。开启 Show Comment 之后方法上方和参数旁边的 Javadoc 会展示出来内容包括name 参数是 bean 的名称、返回值是 bean 实例、可能抛出NoSuchBeanDefinitionException等异常。这些信息原本要按CtrlQ才能看到现在直接铺在代码里。我读源码的习惯是先把一个包下的核心接口扫一遍了解整体能力再深入具体实现。Show Comment 让这个“扫”的过程效率高了很多因为不用反复触发文档弹窗视线是连续的。4.2 场景二调试 JSON 接口对接代码之前做过一个对接物流平台的项目请求参数是一个嵌套三层的 JSON。代码里是这么写的// 构建请求体 // orderNo: 订单号必填 // receiver: 收件人信息对象 // - name: 收件人姓名 // - phone: 手机号11位 // - address: 详细地址不超过100字 String requestBody buildJson(orderNo, receiver);这段注释在 Show Comment 开启后会展示在requestBody变量旁边。调试的时候我不用去翻接口文档直接看代码就知道每个字段的要求。特别是phone要求 11 位这种细节文档里可能写在很不起眼的地方但注释就在眼前。这里有个实操技巧JSON 相关的注释建议用行内注释而不是 Javadoc因为 JSON 构建代码通常是方法内部的局部逻辑用//更自然Show Comment 对行内注释的展示效果也更紧凑。4.3 场景三团队协作中的参数含义确认团队协作里最怕的就是“我以为你知道”。比如一个方法public void updateStatus(Long orderId, Integer status) { ... }status传 1 是待支付、2 是已支付、3 是已发货这些映射关系如果只写在文档里新同事很容易传错。如果写成 Javadoc/** * 更新订单状态 * param orderId 订单主键 * param status 状态码1-待支付2-已支付3-已发货4-已完成 */Show Comment 展示后任何调用这个方法的地方参数旁边都会显示状态码映射。这比口头交代或者翻文档可靠得多而且注释和代码在同一个文件里不会出现文档和代码不同步的问题。4.4 参数配置速查表为了让你配置的时候不用来回翻我把关键配置项和推荐值整理成表配置项推荐值说明展示范围-方法参数开启收益最高的场景展示范围-字段开启阅读实体类时很有用展示范围-局部变量视项目而定算法类项目建议开展示范围-返回值开启了解方法契约注释来源Javadoc 行内两者互补字号与代码一致或小 1px避免视觉突兀颜色浅灰或深灰不要用蓝/绿等关键字色最大长度50 字符超出省略悬停看全斜体开启和代码形成区分这张表可以直接抄装完插件照着设一遍五分钟搞定。5. 常见问题与排查技巧实录5.1 装了插件但看不到注释这是最高频的问题。排查顺序如下第一步确认插件真的启用了。Settings→Plugins→Installed标签页找到 Show Comment看前面的勾有没有打上。有时候装完重启插件处于禁用状态手动勾上再重启一次。第二步确认当前文件类型被支持。Show Comment 主要面向 Java 和 Kotlin如果你打开的是 XML、YAML、Properties 文件它不会展示注释。这是设计如此不是 bug。第三步确认注释格式被识别。Javadoc 必须是/** ... */这种标准格式/* ... */块注释和//行注释的识别规则不同。如果你写的是/* 注释 */可能不会被当作 Javadoc 处理。第四步检查配置里的展示范围。有可能你只开了字段展示但当前看的是方法参数自然看不到。把范围全开试一下。5.2 注释展示位置错乱或重叠偶尔会遇到注释显示在错误的位置或者和代码重叠。这通常是编辑器渲染缓存的问题。解决办法很简单File→Invalidate Caches→ 勾选Clear file system cache→ 重启。我遇到过一次清完缓存就正常了。如果清缓存没用检查一下是不是和其他插件冲突。特别是那些也做代码渲染增强的插件比如某些主题插件、代码折叠插件它们可能都在操作编辑器的渲染层。临时禁用其他插件逐个排查。5.3 大文件下性能下降Show Comment 需要在编辑器渲染时计算每个元素的注释位置文件特别大的时候比如超过 5000 行的类可能会有轻微卡顿。我的应对策略是对大文件临时关闭插件。插件设置里有个“按文件大小自动禁用”的选项设一个阈值比如 3000 行超过就自动关避免影响编辑流畅度。另外如果你用的是机械硬盘IDEA 本身的索引就慢加上插件渲染会更明显。换 SSD 是最直接的改善方式这个和插件无关但值得提一句。5.4 注释内容不更新改了注释之后展示的还是旧内容。这是索引延迟导致的。IDEA 的注释索引不是实时的改完等几秒或者按CtrlS保存一下通常会刷新。如果一直不更新试试Build→Rebuild Project重建索引后肯定是最新的。5.5 常见问题速查表问题现象可能原因解决方法完全看不到注释插件未启用检查 Plugins 列表并重启部分元素无注释展示范围未开在设置中开启对应范围注释位置错乱渲染缓存问题Invalidate Caches 后重启大文件卡顿渲染计算量大设置文件大小阈值自动禁用注释不更新索引延迟保存文件或重建项目和其他插件冲突渲染层竞争逐个禁用排查6. 我个人的使用心得与几个小技巧用了这么久有几个心得是文档里不会写的但实际用起来很关键。第一个技巧注释里用“【】”标记关键信息。比如param id 【必填】用户主键展示出来之后方括号里的内容在视觉上会跳出来比纯文字更容易抓住重点。这个习惯我坚持了很久团队里其他人看到后也跟着用。第二个技巧对重载方法特别有用。一个方法有五个重载版本参数各不相同光看签名很难分清哪个是哪个。如果每个重载的 Javadoc 写清楚了适用场景Show Comment 展示后你扫一眼就知道该调哪个。这在用一些工具类库的时候特别省事。第三个技巧配合“最近文件”功能。我经常在几个核心类之间来回跳Show Comment 让每次跳过去都能立刻进入状态不用重新建立上下文。这个体验很难量化但用久了就回不去了。第四个技巧不要滥用。不是所有注释都值得展示。getter/setter 的注释、显而易见的注释比如// 返回名称对应getName()展示出来只是噪音。我的做法是这类方法的注释尽量精简或者不写把展示空间留给真正需要解释的方法。第五个技巧定期清理过时注释。注释最大的问题是会过期。代码改了注释没改展示出来反而误导人。我养成了一个习惯改方法逻辑的时候顺手看一眼注释不对就改。Show Comment 让过时注释的“曝光率”变高了某种程度上也倒逼了注释质量的维护。最后说一个我踩过的坑。有次我把最大展示长度设成了 200 字符结果一个方法的 Javadoc 特别长展示出来占了半个屏幕代码被挤得没法看。后来改回 50 字符世界清净了。这个参数千万别贪大50 到 80 之间是比较舒服的范围。如果你也在维护一个注释写得不错但平时看不见的项目这款插件值得花十分钟装一下。它不会让你的代码跑得更快但会让你读代码的时候少皱几次眉头。