我应该使用JavaDoc中的过时提示还是Java中的注释？

Question

目前有两种方法可以在Java中将代码标记为已弃用。

通过JavaDoc标记

/**
 * @deprecated
 */

或者作为注释：

@Deprecated

这是我的问题-当在Eclipse中将方法标记为已弃用时，我觉得声明两个有点过于繁琐。 我真的只想使用其中一个。

但是，使用注释会给编译器提供实际有用的额外信息吗？

然而，仅使用注释，我无法说明方法已被弃用的原因-我只能通过JavaDoc来做到这一点，并且不注明方法弃用的原因是不好的。

那么，我只能使用其中一个吗？还是我真的应该学会同时指定两者？

- corgrath

---

如果其他程序员没有你的源代码，他就不会知道你的方法已被弃用。我建议使用@Deprecated注解。 - Eduard

如果另一个程序员没有源代码或Javadocs（还显示注释），那么意外使用不推荐的API只是他问题中最不严重的一种。 - Michael Borgwardt

@Michael Borgwardt，我只是想详细说明可能会带来的问题。这只是我能想到的其中一个问题。有时您可以省略下载源代码和Javadoc并使用已弃用的API，但这些API在下一个版本中将不再存在... - Eduard

Answer 1

你应该同时使用两者。注释使编译器在使用过时方法时显示警告，而javadoc则解释了为什么。这两者都很重要。

根据Oracle的Java注释教程：

当元素被弃用时，应该使用Javadoc @deprecated标记进行文档化...

- Rawrgramming

---

然而，Oracle编译器也会对javadoc标签显示警告，因此该注释其实并不是必需的。 - Michael Borgwardt

@Michael - 在许多情况下（但我想并非全部），可以使用@SuppressWarnings("deprecation")来控制。 - luis.espinal

@MichaelBorgwardt 我理解你的想法，但是过多地这样做最终会导致“不编写文档，因为你只能信任源代码”。例如，javadoc注释确实有其作用，它是唯一可以引导用户使用“替代方案”的地方。 - Edwin Buck

阿门，埃德温。需要两种符号表示的事实确实让人感到不爽。 - ggb667

自JDK 9以来，javac会在没有注释的情况下使用Javadoc标签时发出警告。这是有道理的，因为另一个编译器可能只检查注释。 - Martin

Answer 2

来自权威说明：

注意：Java语言规范要求编译器在使用带有@Deprecated注释的类、方法或字段时发出警告。虽然Java语言规范不要求编译器在访问带@deprecated Javadoc标记的类、方法或字段时发出警告，但Sun编译器目前确实会这样做。

因此，如果您想要保证有编译器发出警告，您需要使用注释。由于某些API设计师令人震惊的无能，您还需要指定javadoc标记以提供解释。

就我个人而言，我认为这个注释是无用的，应该忽略，直到它被修复，因为任何好的编译器或IDE都会显示带有javadoc标记的警告。

- Michael Borgwardt

---

由于任何好的编译器或IDE都会显示带有javadoc标记的警告，因此不错的程序员不会依赖编译器告诉他哪些东西已被弃用，而是寻找新API或更改API的文档说明。 - jwenting

@jwenting，寻找文档是浪费人类时间。让机器自行判断是否发生紧急情况并向您报告，这才是它们的任务。请记住不要改变原文意思，尽可能使翻译通俗易懂。 - thejoshwolfe

@jwenting 我不同意。注释和Javadocs是程序员了解API的一种方式。它们是有效的文档形式。如果可能的话，程序员应该用自己的头脑思考有趣的事情，而不是从不知道哪里寻找文档。 - Andres F.

@jwenting：好的，但特定API被弃用的事实如何成为基础的一部分呢？编译器警告如何指示代码主体中使用弃用API是“预测程序员意图”的呢？ - Michael Borgwardt

我认为最好的做法是，如果@Deprecated注解可以支持一个字符串 'value'，该字符串可以接受有关为何存在此弃用的说明。 说明似乎是使用javadoc方式而不是注释本身的唯一原因。 - jrharshath

Answer 3

你应该同时编写两个标记。@Deprecated注释是为编译器而设计的，而@deprecated JavaDoc标记则是为想要了解为什么会被弃用的人而设计的。

一个示例可能如下所示：

/**
* @deprecated We dont need this Method because ...
*/
@Deprecated
public void doStuff(){..}

- Marcel

---

对于编译器来说，编译器除了向开发人员发出警告之外并不关心这些（注释和Javadoc评论），所以它们都是为开发人员准备的。只是注释本身几乎没有用处，而Javadoc评论则不能保证被使用。因此，Sun/Oracle（我不知道这是谁负责的）创建了一个情况，在这种情况下，开发人员必须执行两个不同的操作才能充分记录情况，而本应仅需要一个操作就足够了。 - nasch

这两个答案都很准确。你应该使用两个，但只需要使用一个就可以了。 - thonnor

Answer 4

你应该同时指定两个。

注解让编译器知道这一点，并在使用该方法时触发警告。JavaDoc属性让开发人员在开始使用之前了解它。

这是两件非常不同的事情！

- Dunaril

---

这些其实并不是完全不同的事情。如果注释允许将解释作为参数，那么开发人员也可以查看它。 - Michael Borgwardt

@Michael，你的回答强调了它们之间的区别。实际上，它甚至发展了与我的相同的想法。 - Dunaril

不，我的回答强调了Javadoc标签仍然是必要的，只因为该注释设计得不好。注释是代码元数据和开发人员的信息，就像方法签名一样。 - Michael Borgwardt

需要2个标签是愚蠢的。注释不应该存在，因为没有文档，它几乎毫无价值。事实上，我现在想知道为什么这个特定的东西被标记为过时了。没有@Deprecated javadoc标签，所以我不知道。这太糟糕了。它几乎比没有好，因为有人曾经说“不要使用它”，但没有解释原因。忍不住想扼杀它。 - ggb667

Answer 5

这可以通过一个好的IDE轻松处理。

例如，Eclipse Neon在我创建一个方法或字段的javadoc @deprecated时自动添加@Deprecated注释。

因此，我只需写出适当的解释并让IDE在保存文件时立即添加@Deprecated注释即可。

- Inxsible