java - 如何正确使用FindBugs的@CheckForNull、@Nonnull和@Nullable注解

Question

我想正式注释我的函数签名以阐明它们的契约——特别是如果 null 参数和返回值被允许或禁止——以 FindBugs 的静态代码分析工具(可能还有其他工具)的方式) 可以利用它。

有两个包(annotations.jar 和 jsr305.jar)，每个包有四个注释来实现这一点，以及根本不放置注释的选项.

Answer 1

这些是我经过一番尝试后的发现:

方法参数:

• 参数不能为null:不要放置任何注释。在这种情况下，如果将null 传递给方法，则会出现错误标记. (我在放置 @Nonnull 注释时预料到了这种行为，但是当我放置它时，根本没有错误标记出现。)
• 参数可以为null:放置@Nullable注解。(与@CheckForNull效果相同。@Nullable documentation 读取:“FindBugs 会将带注释的项目视为没有注释。”这是不正确的。如果我调用 string.length() 和 String string 被标记为@Nullable，它会导致错误标记出现，如果没有注释则不会显示错误标记。)

方法返回值:

• 方法从不返回 null:放置 @Nonnull。 如果您尝试 return null； 会导致错误标记> 从方法内部。
• 方法可以返回null:你想强制检查它吗？如果返回值确实仅依赖于调用时已知的方法参数，则检查可能会产生开销，例如“如果参数一为负数，我的方法将返回 null”。在那种情况下我不会添加注释。但是，您可能需要考虑抛出 IllegalArgumentException 而不是返回 null。
• 方法可以返回 null 并且应该始终检查返回对象:放置 @CheckForNull。但是，在许多情况下有更好的方法去，你可能要考虑返回 Collections.emptyList() 而不是 null 列表，或者抛出 MissingResourceException、IOException 或其他适当的异常。

使用哪个 JAR 文件:

• 这两个 jar 文件都会导致相同的 FindBugs 行为，唯一的区别是来自 annotations.jar 的注释在 Eclipse 中显示为已弃用。所以使用jsr305.jar。
• 需要 jar 文件。使用给定的包和类名称创建空注释不起作用。你可以get it here .