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


78

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

通过JavaDoc

/**
 * @deprecated
 */

或作为注释:

@Deprecated

这是我的问题-在使用Eclipse将方法标记为不推荐使用时,要声明两者都太多了。我真的只想使用其中之一。

但是,使用注释是否会为编译器提供实际有用的其他信息?

但是,仅使用注释,就无法说明为什么不赞成使用该方法-我只能使用JavaDoc来做到这一点,并且不赞成说明为什么不赞成使用不赞成使用的方法。

因此,我只能使用其中之一吗?或者我真的应该学会同时指定两者吗?


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

1
@ t-edd:如果其他程序员没有源代码或javadocs(也显示注释),则不希望使用已弃用的API最少。
Michael Borgwardt

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

Answers:


75

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

按照Oracle的Java注释教程

不推荐使用元素时,还应使用Javadoc @deprecated标记对其进行记录。


5
但是,Oracle编译器也会为javadoc标记显示警告,因此实际上并不需要注释。
Michael Borgwardt

@Michael-在很多情况下(但不是我能想象的),可以使用@SuppressWarnings("deprecation")
luis.espinal

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

3
阿门·埃德温(Amen Edwin)。需要2个标记的事实很糟糕。
ggb667

@MichaelBorgwardt自JDK 9起, javac抱怨如果使用Javadoc标记而不使用注释。这是有道理的,因为另一个编译器可能只是检查注释。
马丁

37

马口中

注意:Java语言规范要求编译器在使用标有@Deprecated批注的类,方法或字段时发出警告。Java语言规范不需要编译器在访问带有@deprecated Javadoc标记的类,方法或字段时发出警告,尽管Sun编译器当前正在这样做。

因此,基本上,如果要保证会有编译器警告,则需要使用批注。并且由于某些API设计人员的惊人能力,您还需要指定javadoc标记以进行说明。

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


3
“因为任何好的编译器或IDE都将显示带有javadoc标记的警告。” 而且任何体面的程序员都不会依赖编译器来告诉他有关过时的内容,他会寻找新的或更改的API的文档。
jwenting 2011年

12
@jwenting,查找文档是在浪费时间。让机器弄清楚是否发生了警报,并告诉您有关情况。那是他们的工作。
thejoshwolfe

2
@jwenting我不同意。注释和javadocs是程序员“了解” API的一种方式。这是有效的文档形式。程序员应该尽可能地发挥自己的才智来思考有趣的东西,而不是从谁知道哪里的地方去寻找文档。
Andres F.

3
@jwenting:好的,但是基础知识中不赞成使用特定的API的事实又如何呢?编译器警告如何指示在代码体中使用已弃用的API,“从而可以预测程序员的意图”?
Michael Borgwardt'2

8
我想最好的办法是,如果@Deprecated批注可以支持字符串“ value”,该字符串可以接受有关为何弃用的解释。这种解释似乎是使用javadoc方式而不是注释本身的唯一原因。
jrharshath 2013年

5

您应该同时指定两者。

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

这是两个截然不同的东西!


6
这些根本没有什么不同。如果注释允许将解释作为参数,那么也可以将其显示给开发人员。
Michael Borgwardt

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

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

2
需要两个标签是愚蠢的。注释不应该存在,因为如果没有文档,注释将几乎一文不值。实际上,我现在想知道为什么将此特定事物标记为已弃用。没有@Deprecated javadoc标记,所以我不知道。糟透了 这几乎比没有要糟,因为有人有时说“不要使用它”,而不是为什么。敦促扼杀上升。
ggb667 2013年

5

您应该两者都写。@Deprecated注释用于编译器,而@deprecated JavaDoc标记用于希望现在为什么不建议使用此方法的人员。

一个示例如下所示:

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

2
对于编译器?编译器只关心向开发人员发出警告,因此它们都是针对开发人员的。只是注释本身几乎没有用,而不能保证使用javadoc注释。因此,Sun / Oracle(我不知道这是谁的监视对象)设置了一种情况,开发人员必须做两件不同的事情才能充分记录该情况,而本来应该足够。
nasch 2015年

这两个答案都是正确的。您应同时使用两者,但仅需使用其中之一。
thonnor

1

一个好的IDE可以很容易地解决这个问题。

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

因此,我只需编写带有适当说明的javadoc,然后让IDE负责在保存文件的那一刻添加@Deprecated批注。

By using our site, you acknowledge that you have read and understand our Cookie Policy and Privacy Policy.
Licensed under cc by-sa 3.0 with attribution required.