要写注释？ 使用 IntelliJ IDEA 让您的代码注释更专业

Sue

Read this post in other languages:

• English
,
• 한국어

可能很多开发者会对这篇文章的标题嗤之以鼻。 毕竟，专业开发者不需要注释就能写出自己看得懂、别人也看得懂的代码。 只不过，这谈何容易？ 因此，本文要讲的就是如何才能快速有效地注释代码。

代码中有多种类型的注释，并不是所有注释都暗示代码有异味。

如果代码不好读，或者可能需要进一步处理，留下注释就可以让我们自己或团队的其他成员更好地理解代码。 在开源项目中，开发者们往往具有不同的背景，使用注释能够避免混乱和困惑，节省大量时间。

如果某段代码暂时需要被“隐藏”起来，但不至于被删除，那么注释也能派上用场。

为其他国家/地区本地化应用程序时，我们还会在 .properties 文件中注释属性。 如果属性包含串联或变量，注释就必不可少。

如果代码有改进的空间，我们就可以给自己或他人留下 TODO 注释。 在针对可以更改的内容添加快速注释时，无需离开 IDE。

文档注释是代码中的另一种注释。 以 Javadocs (/**...*/) 为例， 它们最大的好处是，后续只需点击几下鼠标就可以从注释中生成合适的 API 引用。

Javadocs 值得另起一篇博文单独介绍，因为要涵盖的内容实在太多了。 现在，我们先来看澄清注释和 TODO 注释。

行和块注释

Java 中的单行注释以两个正斜杠 (//) 开头。 要在 IntelliJ IDEA 中快速添加行注释，在 macOS 上按 ⌘ /，或者在 Windows 和 Linux 上按 Ctrl + /。

块注释或多行注释通常采用段落的形式。 存在例外，例如向代码行中间插入注释时。 在这种情况下，无论注释需要多短，多行注释都是唯一的选择。

块注释会被斜线-星号 (/*) 和星号-斜线 (*/) 括起来。 要在 IntelliJ IDEA 中添加块注释，在 macOS 上按 ⌥ ⌘ /，在 Windows 和 Linux 上按 Ctrl + Shift + /。

IntelliJ IDEA 中的一个快速修复可以完成行注释和块注释之间的转换。 将文本光标放在注释上，然后，在 Windows 和 Linux 上按 Alt+Enter，在 macOS 上按 Option+Enter，选择 Replace with end-of-line comment（替换为行尾注释）或 Replace with block comment（替换为块注释）。

在建议列表打开时按 F1 可以预览变更。

相同的快捷键也可以用来撤消行的注释。

注释可以在行首生成，也可以与代码对齐。 此外，您可以配置 IDE，让它在您添加新注释时于注释符号和注释文本之间添加空格。 在块注释中，文本前后都会添加一个空格。

您可以在 Preferences / Settings | Editor | Code Style | Java | Code Generation | Comment Code（偏好设置 / 设置 | 编辑器 | 代码样式 | Java | 代码生成 | 注释代码）中配置这些设置。

在即将发布的 IntelliJ IDEA 2022.1 中，我们添加了一项新功能，它可以在您于 Java、Kotlin 和 Groovy 中重新格式化代码时在行注释中添加空格。 最新的 EAP 版本已经提供功能试用。

TODO 注释

如果您发现了需要额外注意的代码，但您又不想为了给自己或团队写注释而离开编辑器，那就该用 TODO 注释了。

IntelliJ IDEA 默认提供两种预定义模式：包含 TODO (//TODO) 的注释和包含 FIXME (//FIXME) 的注释。 您可以使用正则表达式创建自己的模式。 为此，请创建一个实时模板，将自定义 TODO 快速插入到代码中。

IntelliJ IDEA 在一个工具窗口中收集所有 TODO 注释，确保注释不会遗失在代码库中。 它们也在编辑器中高亮显示，并在编辑器右侧的错误条上标有记号。 要查看所有 TODO 注释，请从主菜单中选择 View | Tool Windows | TODO（视图 | 工具窗口 | TODO）。

额外福利

IntelliJ IDEA 还会在代码库中自动搜索自然语言文本中的语法和拼写错误， 甚至针对不恰当的样式发出警告。 在带下划线的单词上按 Alt+Enter / Option+Enter 即可查看可用建议。 在试用此功能之前，请确保已启用捆绑的 Grazie 插件。

代码中的注释用途不一。有时只是辅助，有时则极其关键。IntelliJ IDEA 可以帮助您根据需要留下有意义的注释。

您有什么想法？您经常在代码中留注释吗？在评论区告诉我们吧！

祝您开发愉快！

本博文英文原作者：

Subscribe to IntelliJ IDEA Blog updates

Subscribe form

By submitting this form, I agree to the JetBrains Privacy Policy Notification icon

提交此表单，即表示我同意 JetBrains s.r.o. ("JetBrains") 使用我的姓名、电子邮件地址和位置数据向我发送简报和商业通讯，并为此目的而处理我的个人数据。我同意 JetBrains 根据 JetBrains 隐私政策为此目的使用第三方服务处理上述数据。我了解我可以在我的个人资料中随时撤回此同意。此外，每封电子邮件中也都包含退订链接。

Submit

谢谢！