Java：“尚未实现”的通用注释答案

【问题标题】：Java: Common Annotation for "Not Yet Implemented"Java：“尚未实现”的通用注释
【发布时间】：2012-04-16 13:55:16
【问题描述】：

Java 中是否有一个通用的或标准的注解，用于定义已定义但尚未实现的方法？

因此，例如，如果我使用的是包含类似内容的库的 pre-alpha 版本

@NotImplementedYet
public void awesomeMethodThatTotallyDoesExactlyWhatYouNeed(){ /* TODO */ }

我在尝试调用 awesomeMethodThatTotallyDoesExactlyWhatYouNeed 时会收到编译时警告？

【问题讨论】：

大多数库根本不会公开该方法。有什么意义？
我遇到过，as a user。也许是为了让未来的 API 成为一个想法，让用户为它做好准备？
当然，您可以创建自己的“@NotImplementedYet”注解，并随心所欲地使用它：docs.oracle.com/javase/1.5.0/docs/guide/language/…
相关：Is there anything like .NET's NotImplementedException in Java?

标签： java annotations

【解决方案1】：

您可能希望在运行测试时使用UnsupportedOperationException 并检测对尚未实现的方法的调用。

【讨论】：

OP 正在寻找一个注释，它将在编译时告诉调用者该方法将抛出 UnsupportedOperationException。由于另一方创建这样的注释很容易，他正在寻找被接受为约定的东西
不完全是要求的解决方案，但总比没有好，而且有些正交（在其他方面更好）。

【解决方案2】：

您可以创建自己的注释。使用运行时保留策略，您可以将目标构建配置为知道在必要时查找此注释。

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target({
    ElementType.ANNOTATION_TYPE, 
    ElementType.METHOD, 
    ElementType.CONSTRUCTOR,
    ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
public @interface Unimplemented {

    boolean value() default true;
}

【讨论】：

【解决方案3】：

Google guava 库对 API 使用 @Beta 注释，这可能会改变，但方法已实现

【讨论】：

【解决方案4】：

没有，没有专门针对尚未实现的方法的标准注释。

不过，JDK 中有一个更通用的注解，标记了不鼓励开发人员使用的 API，Java 编译器本身在使用时会发出警告。我说的是@Deprecated，许多开发人员只认为是“宣布删除”。但是，JDK 文档中的相关文章（例如 Java 7 和 Java 9）列出了几个示例用例，其中只有一个是关于删除的：

API 很危险（例如，Thread.stop 方法）。

有一个简单的重命名（例如，AWT Component.show/hide 替换为setVisible）。

可以使用更新、更好的 API。

将删除已弃用的 API。

我认为您的案例“尚未实施”肯定与那些情况相同。此外，如果该方法总是throw a NotYetImplementedException，它甚至适合示例“API 很危险”。

所以你需要做的就是：

在方法中添加@Deprecated
添加@deprecatedJavadoc说明背景
将您的构建配置为使用-Xlint:deprecation 调用编译器，以便它发出警告。

【讨论】：