如何注释Java中的类的弃用? [英] How to annotate deprecation of a class in Java?

问题描述

我将弃用 Java 中的一个类.

I am going to deprecate a class in Java.

@Deprecated
class deprecatedClass

我有这个不推荐使用的类的列表，

and I have list of this deprecated class,

List<deprecatedClass> listOfDeperecatedClass

那么我还需要为这个列表添加 @Deprecated 标签吗?

So do I need to add the @Deprecated tag for this list too?

@Deprecated 应该有一个大写的D".
请参阅:http://docs.oracle.com/javase/7/docs/api/java/lang/Deprecated.html

@Deprecated should have a capital 'D'.
See: http://docs.oracle.com/javase/7/docs/api/java/lang/Deprecated.html

推荐答案

不，你不需要.将注解 @Deprecated 添加到 DeprecatedClass 将在每次使用时生成警告.

No, you don't need to. Adding the annotation @Deprecated to DeprecatedClass will generate a warning every time it's used.

您应该做的是将other类中的方法标记为将您已弃用的类作为参数或将其返回为已弃用的方法.这适用于其他代码可能对您已弃用的类的实例的任何访问 —公共字段、常量等.当然，如果没有您已弃用的类的实例，就不能使用这些，因此无论如何都会给出警告，但是在正确的弃用注释和评论中，您应该提供解释并指出替代方案，这是您的宝贵信息 需要给予.

What you should do however, is marking methods in other classes that take your deprecated class as an argument or return it, as deprecated as well. That goes for any access that other code may have to instances of your deprecated class — public fields, constants and so on. Those of course can't be used without an instance of your deprecated class, so the warning is given anyway, but in a correct deprecation annotation and comment, you should provide an explanation and point to an alternative, which is valuable information you need to give.

方法签名类似于合同，类签名也是如此.您是在告诉其他程序员他们可以调用哪些方法以及如何调用它们.您是在告诉他们哪些字段可以访问.其他程序员以此为基础编写代码.如果您确实需要打破该合同，您首先需要提供该合同的替代品(具有相同功能的新方法)，并告诉他们并给他们时间切换到该新合同(弃用旧方法和类).

A method signature is like a contract and so is a class signature. You're telling other programmers what methods they can call and how they can call them. You're telling them which fields are accessible. Other programmers base their code on that. If you really need to break that contract, you first need to provide a substitute for that contract (a new method with the same functionality), and tell them and give them time to switch to that new contract (deprecate the old methods and classes).

当然，以上假设您正在为受众编写代码.如果您是唯一使用您的代码的人，并且您只想弃用以清理代码而不破坏构建，只需弃用该类，修复警告并将其删除.

Of course, the above assumes that you're coding to an audience. If you're the only one using your code and you just want to deprecate to clean up your code without breaking the build, just deprecate the class, fix the warnings, and remove it.

这篇关于如何注释Java中的类的弃用?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！