我应该使用 JavaDoc 弃用还是 Java 中的注释？

java annotations javadoc deprecated

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

通过 JavaDoc

/**
 * @deprecated
 */

或作为注释：

@Deprecated

这是我的问题 - 在使用 Eclipse 时将方法标记为已弃用时，我发现两者都声明有点过多。我真的只想使用其中之一。

但是，使用注解是否会给编译器提供实际有用的附加信息？

但仅使用注释，我无法说明为什么不推荐使用该方法 - 我只能使用 JavaDoc 来做到这一点，并且在不指定原因的情况下不推荐使用方法是不好的。

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

如果其他程序员没有你的资源怎么办？他不会知道您的方法已被弃用。我会说使用注释@Deprecated

@t-edd：如果其他程序员既没有源代码也没有 javadocs（它也显示注释），那么意外使用不推荐使用的 API 是这个问题中最少的。

@Michael Borgwardt 我只是想详细说明它会带来什么问题。这只是我能想到的一个。有时您可以省略下载源代码和 javadoc 并使用不推荐使用的 api，它不会出现在下一个版本中......

sheldonh

你应该同时使用两者。 Annotation 允许编译器在使用不推荐的方法时显示警告，javadoc 解释了原因。两者都很重要。

根据 Oracle 的 Java 注释 tutorial：

当一个元素被弃用时，它也应该使用 Javadoc @deprecated 标记来记录......

但是，Oracle 编译器也会对 javadoc 标记显示警告，因此实际上不需要注释。

@Michael - 在很多情况下（但不是我想象的全部），这可以通过 @SuppressWarnings("deprecation") 来控制

@MichaelBorgwardt 我理解您的想法，但是其中太多最终会导致“无论如何都不要编写文档，因为您只能信任源代码”。 javadoc 注释确实有一个目的，例如，它是唯一可以指导用户“改用此替换”的地方。

阿门埃德温。不过，需要 2 个符号这一事实很糟糕。

@MichaelBorgwardt Since JDK 9 javac 如果在没有注释的情况下使用 Javadoc 标记，则会抱怨。这是有道理的，因为另一个编译器可能只是检查注释。

Michael Borgwardt

从 horse's mouth：

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

所以基本上，如果你想保证会有编译器警告，你需要使用注解。而且由于某些API设计者的无能，您还需要指定javadoc标签以进行解释。

就个人而言，我会说注释是无用的，应该在修复之前将其省略，因为任何好的编译器或 IDE 也会显示带有 javadoc 标记的警告。

“因为任何好的编译器或 IDE 也会显示带有 javadoc 标记的警告。”任何体面的程序员都不会依赖编译器来告诉他不推荐使用的东西，他会寻找新的或更改的 API 的文档。

@jwenting，寻找文档是在浪费人的时间。让机器弄清楚是否发生了令人震惊的事情并告诉你。那是他们的工作。

@jwenting 我不同意。注释和 javadocs 是程序员“了解”API 的一种方式。这是一种有效的文档形式。只要有可能，程序员应该使用他/她的脑力去思考有趣的东西，而不是去寻找不知道在哪里的文档。

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

我想最好的办法是@Deprecated 注释可以支持字符串“值”，该字符串可以接受对弃用原因的解释。这种解释似乎是人们使用 javadoc 方式而不是注释本身的唯一原因。

Marcel

你应该两个都写。 @Deprecated 注释用于编译器，@deprecated JavaDoc 标记用于想知道为什么不推荐使用的人。

一个示例可能如下所示：

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

对于编译器？除了向开发人员发出警告之外，编译器并不关心，所以它们都是为开发人员准备的。只是注解本身几乎没用，而javadoc注释不保证能用。因此，Sun/Oracle（我不知道这是谁的手表）设置了一种情况，即开发人员必须做两件不同的事情来充分记录本应足够的情况。

这两个答案都是正确的。您应该同时使用两者，但只需要使用一个。

Dunaril

您应该同时指定两者。

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

这是两种截然不同的东西！

这些根本不是不同的东西。如果注释允许解释作为参数，那么也可以向开发人员显示。

@Michael您自己的回答强调了它们之间的区别。实际上，它甚至与我的想法相同。

不，我的回答强调仍然需要 javadoc 标记，只是因为注释设计不当。注释是开发人员的代码元数据和信息，就像方法签名一样。

需要 2 个标签是愚蠢的。注释不应该存在，因为没有文档，它几乎一文不值。事实上，现在我想知道为什么这个特定的东西被标记为已弃用。没有@Deprecated javadoc 标签，所以我不知道。这很糟糕。这几乎比没有更糟糕，因为有时有人说“不要使用它”，但不是为什么。敦促扼杀上升。

Inxsible

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

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

因此，我只需编写带有适当解释的 javadoc，并在我保存文件的那一刻，让 IDE 负责添加 @Deprecated 注释。

我应该使用 JavaDoc 弃用还是 Java 中的注释？

关注公众号

想领先一步获取最新的外包任务吗？

相似问题

平台

支持

联系我们