注释
最后修改时间:2023 年 9 月 7 日注释是元数据片段,提供有关代码元素(例如类、方法或参数)的信息。
在Java中,有一组内置的注释。此外,许多库和框架(例如 Spring 和 Lombok)定义了自己的注释。这些注释提供的元数据可以在编译时和运行时使用,例如,生成样板代码,或通过反射与用户类交互。
代码合约注释
还有一类描述代码语义和契约的注释。开发人员可以使用它们更好地理解使用特定 API 的含义,并帮助静态分析器识别有问题的区域。
IntelliJ IDEA 可以识别流行的 Java 注释,并在分析代码时将其考虑在内。此类注释框架的示例包括Checker Framework和ErrorProne
可空性注释
可空性注释是代码契约注释的子集。通过显式声明元素的可为空性,代码将变得更易于维护,并且不易出现与可为空性相关的错误。
另一方面,IntelliJ IDEA 的静态分析将使用这些注释来捕获设计时的潜在错误。例如,IntelliJ IDEA 将分析项目中的数据流,并报告对可能存在的变量进行取消引用的尝试null
,反之亦然,建议在可以安全删除的情况下删除多余的保护条件。
配置可空性注释
虽然 IntelliJ IDEA 可以识别流行的可空性注释,但您可能仍然希望将自定义注释添加到列表中。然后,IntelliJ IDEA 将使用它们来确定符号的可为空性。
转到设置 | 编辑| 检查 | 可能的错误 | 可空性和数据流问题。
在“选项”下,选择“配置注释”。
禁用可空性断言
当您编译项目时,IDE 会将断言添加到所有用@NotNull
. 如果元素恰好在null
运行时,这些断言将引发错误。这种快速失败行为可以帮助您在早期阶段诊断问题。如果这不是您想要的效果,您可以禁用这些断言。
转到设置| 构建、执行、部署 | 编译器CtrlAlt0S并取消选中为 notnull-annotated 方法和参数添加运行时断言选项。
推断无效
如果您的项目完全或部分缺少可空性注释,您可以让 IntelliJ IDEA 为您推断并插入可空性注释。
确保为您的项目配置了带有注释的库。IntelliJ IDEA 使用设置|中用于代码生成的注释中指定的注释。编辑| 检查 | 可能的错误 | 可空性和数据流问题| 配置注释。
提示
如果您想使用JetBrains 注释,并且您正在使用 IntelliJ IDEA 构建工具,IDE 将检测缺少的依赖项并建议自动添加它
转到代码| 分析代码 | 推断无效。
在“指定推断无效范围”对话框中,选择分析范围。如果要包含测试源或注释局部变量,请选择相应的复选框。
JetBrains 注释依赖项
IntelliJ IDEA 有自己的注释集,可作为单独的依赖项使用。它包含用于表达可空性、范围、契约、可变性、纯度等的注释。
该包由几十个注释组成。一些最常见的是:
@Nullable
and@NotNull
– 表示变量、参数或返回值可以为空或不能为空。@Nls
– 表示带注释的代码元素是需要本地化的字符串。@NonNls
– 表示带注释的代码元素是用户不可见的字符串,不需要本地化,并且不包含需要本地化的字符串。当您使用 注释元素时@NonNls
,本地化工具将跳过该元素及其内部的字符串。@PropertyKey
– 指示方法参数接受的参数必须是特定资源包中的有效属性键。当不是包中属性键的字符串文字作为参数传递时,IntelliJ IDEA 将其突出显示为错误。该注释还用于提供作为参数传递的字符串文字的补全。@TestOnly
– 指示只能从测试代码中调用方法或构造函数。@Contract
– 允许您指定方法必须遵循的一组规则(契约)。如果违反合同,IntelliJ IDEA 会报告问题。@Language
– 在 Java 字符串中注入用另一种语言编写的代码。
笔记
有关完整注释的描述,请使用快速文档或参考包存储库。Ctrl0Q
将 JetBrains Annotations 依赖项添加到项目中
当您在代码中使用 JetBrains 注释时,将“注释”添加到类路径意图操作将帮助您快速添加所需的依赖项。
否则,您可以使用以下工件坐标手动添加它:https://central.sonatype.com/artifact/org.jetbrains/annotations/24.0.1
梅文Gradle Groovy摇篮KotlinIntelliJ IDEA 构建工具<dependencies> <dependency> <groupId>org.jetbrains</groupId> <artifactId>annotations</artifactId> <version>24.0.0</version> </dependency> </dependencies>
dependencies { implementation 'org.jetbrains:annotations:24.0.0' }
dependencies { implementation("org.jetbrains:annotations:24.0.0") }
转到项目结构 | 图书馆CtrlAltShift0S。单击,然后选择来自 Maven。在搜索字段中,输入
org.jetbrains:annotations:24.0.0
。单击“确定”。警告
对于 JDK 1.5 到 1.7,请使用annotations-java5工件。
推断注释
如果代码根本没有注释,IntelliJ IDEA 仍然可以从字节码和源中推断出许多注释。这些注释并未实际插入到代码中,但 IDE 会显示它们,就好像它们已就位一样,以帮助您更好地理解代码联系。就像常规注释一样,推断的注释也可用于代码分析。
IntelliJ IDEA 可以推断以下JetBrains 注释:@Nullable
、@NotNull
、@Contract
、@Unmodifiable
和@UnmodifiableView
。有关此注释风格的完整文档,请参阅包源代码。
笔记
如果您为代码生成指定了自定义可空性注释,则将推断它们而不是 JetBrains 的注释。
在编辑器中,推断的注释在装订线中用 图标标记。
在代码中添加推断注释
如果您想在代码中实际插入推断注释,请单击所需注释附近的 ,然后选择“插入”。
显示内联推断注释
您可以将 IDE 配置为在代码中显示推断的注释。
按打开 IDE 设置,然后选择编辑器 | 镶嵌提示| 注释 | 爪哇。CtrlAlt0S
选择推断注释复选框。
提示
如果稍后需要隐藏注释,可以使用相同的设置,或者只需右键单击注释提示并选择“关闭推断注释”。
外部注释
如果您想显式使用注释,但不希望它们使您的代码库混乱,也可以将它们存储在外部。您可以选择将带有注释的文件提交到公共存储库或将它们专门保留在本地环境中。
外部注释是存储在源代码外部名为annotations.xml的XML 文件中的常规注释。
您可能想要使用它们的常见情况是:
在一个成员使用不同 IDE 和静态分析工具的团队中工作
注释其来源无法更改的代码,例如库类
保持代码中没有用于特定目的的注释(例如,@Async.Schedule/Execute或@DebugRenderer)。
在代码中,外部注释用装订线图标标记,并以灰色突出显示。默认情况下,IntelliJ IDEA 在编辑器中显示外部注释。
启用外部注释
要使用外部注释,您需要在设置中启用它们。如果跳过此步骤,您将能够在外部注释库代码,但无法在源代码中使用外部注释。
按打开 IDE 设置,然后选择编辑器 | 代码风格| 爪哇 | 代码生成。CtrlAlt0S
选中使用外部注释复选框。
添加外部注释
通过以下方式之一指定外部注释:
使用项目代码时,您可以键入注释,然后使用注释外部意图操作。要访问意图操作菜单,请将脱字符号放在注释处并按(或单击意图操作图标)。AltEnter
另一种可用于项目代码和库的替代方法是对元素本身使用注释意图操作。
根据当前上下文中可用的注释,IntelliJ IDEA 将允许您从菜单中选择所需的注释,或者,如果只有一个注释可用,建议立即插入它。
如果尚未为您的项目或模块配置注释目录,IntelliJ IDEA 将提示您进行设置。
您在此模块中添加的每个外部注释都将存储在该文件夹中。如果您有多个注释根,IntelliJ IDEA 会询问您使用哪一个。
您可以稍后更改此位置。
删除外部注释
单击带注释的元素附近的装订线图标,然后选择Deannotate。
配置注释根目录
注释根目录是存储外部注释的文件夹。根据它们所应用的项目部分,它们被配置在不同的位置。
对于整个项目:项目结构| SDK | 注释CtrlAltShift0S
对于各个模块:项目结构| 模块 | 路径| 外部注释CtrlAltShift0S
对于外部 Maven/Gradle 依赖项:项目结构| 模块 | 依赖关系 | 注释CtrlAltShift0S
隐藏外部注释
默认情况下,外部注释显示在编辑器中。您可以在代码中隐藏它们:
右键单击外部注释,然后禁用显示外部注释选项。当嵌入提示被隐藏时,只有装订线中的图标标记它们在代码中的存在。
如果您想稍后启用嵌入提示,可以在“设置”| “设置”中进行。编辑| 镶嵌提示| 爪哇CtrlAlt0S
感谢您的反馈意见!