如何正确使用FindBugs的@CheckForNull,@ Nonull和@Nullable注释

Question

我想正式注释我的函数签名以澄清他们的契约 - 特别是如果null允许或禁止params和返回值 - 以FindBugs的静态代码分析工具(可能还有其他)可以使用它的方式.

有两个包(annotations.jar和jsr305.jar),每个包含四个注释,以及不添加注释的选项.

Answer 1

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

方法参数:

• 参数不能是null:不要放任何注释.在这种情况下,如果null传递给方法,则会出现错误标记.(我在放置@Nonnull注释时曾经预料到这种行为,但是当我把它放进去时,根本没有出现错误标记.)
• 参数可以是null:放置@Nullable注释.(相同的效果@CheckForNull.@Nullable 文档内容如下:"FindBugs会将带注释的项目视为没有注释."这不是真的.如果我调用string.length()并且String string已经标记@Nullable,则会导致出现错误标记,如果没有注释没有错误标记显示.)

方法返回值:

• 方法永不返回null:放@Nonnull.如果您尝试return null;从方法内部导致错误标记.
• 方法可以返回null:您是否要对其执行检查？如果返回值确实取决于只能在调用时可以假设的方法参数,则检查可能是开销,例如" null如果参数1为负,则我的方法返回".在这种情况下我不会给出注释.但是,您可能需要考虑投掷IllegalArgumentException而不是返回null.
• 方法可以返回null并且应该始终检查返回对象:Put @CheckForNull.然而,在许多情况下有更好的方式去,你可能要考虑回国Collections.emptyList(),而不是null列表,或抛出MissingResourceException,IOException或其他适当的异常.

要使用哪个JAR文件:

• 两个jar文件都会导致FindBugs的相同行为,唯一的区别是annotations.jarEclipse 中的注释显示为已弃用.所以使用jsr305.jar.
• 需要jar文件.使用给定的包和类名创建空注释不起作用.你可以在这里得到它.