我应该使用 JavaDoc 弃用还是 Java 中的注释?
目前,有两种方法可以在 Java 中将代码标记为已弃用。
通过 JavaDoc
/**
* @deprecated
*/
或作为注释:
@Deprecated
这是我的问题 - 在使用 Eclipse 时将方法标记为已弃用时,我发现同时声明两者有点太多了。我真的只想使用其中之一。
但是,使用注释是否可以为编译器提供实际有用的附加信息?
但仅使用注释,我无法说明为什么该方法被弃用 - 我只能使用 JavaDoc 来做到这一点,并且弃用一个方法而不指定原因是不好的。
那么,我可以只使用其中之一吗?或者我真的应该学会指定两者吗?
There are at the moment, two ways to mark code as depreacted in java.
Via JavaDoc
/**
* @deprecated
*/
Or as an annotation:
@Deprecated
This is my problem - I find it a bit too much to declare both, when marking a method as deprecated when using Eclipse. I really just want to use one of them.
However does using the annotation give the compiler actual useful additional information?
But only using the annotation, I cannot state why the method is deprecated - I can only do that with JavaDoc, and deprecating a method without specying why is bad.
So, can I only use one of them? Or should I really just learn to specify both?
如果你对这篇内容有疑问,欢迎到本站社区发帖提问 参与讨论,获取更多帮助,或者扫码二维码加入 Web 技术交流群。

绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱,如果其他用户或者作者回复了您的评论,将不能在第一时间通知您!
发布评论
评论(5)
你应该同时使用两者。注释允许编译器在使用不推荐使用的方法时显示警告,并且 javadoc 解释了原因。两者都很重要。
根据 Oracle 的 Java Annotations 教程:
You should use both. The Annotation allows the compiler to display a warning whenever a deprecated method is used, and the javadoc explains why. Both are important.
As per Oracle's Java Annotations tutorial:
来自马口:
所以基本上,如果你想保证会有编译器警告,你需要使用注释。而且由于某些 API 设计者的惊人无能,您还需要指定 javadoc 标签来给出解释。
就我个人而言,我认为该注释是无用的,在修复之前应该将其省略,因为任何好的编译器或 IDE 也会显示带有 javadoc 标记的警告。
From the horse's mouth:
So basically, if you want a guarantee that there will be compiler warnings, you need to use the annotation. And because of some API designer's breathtaking incompetence, you need to specify the javadoc tag as well to give an explanation.
Personally, I'd say the annotation is useless and should be omitted until it's fixed, since any good compiler or IDE will display warnings with the javadoc tag as well.
你应该两者都写。
@Deprecated 注释适用于编译器,@deprecated JavaDoc 标记适用于想要知道为什么不推荐使用它的人。
一个例子如下:
You should write both.
The @Deprecated Anotation is for the Compiler and the @deprecated JavaDoc tag is for the Person who wants to know why this is deprecated.
An example can look like this:
您应该指定两者。
该注释让编译器知道它并在使用该方法时触发警告。
JavaDoc 属性让开发人员在开始使用之前了解它。
这是两个截然不同的事情!
You should specify both.
The annotation lets the compiler know about it and trigger warnings when the method is used.
The JavaDoc attribute lets developers know about before they start using it.
These are two very different things!
一个好的 IDE 可以轻松解决这个问题。
Eclipse Neon,例如。当我在方法或字段上创建 javadoc @deprecated 时,会自动添加 @Deprecated 注释。
因此,我只需编写带有适当解释的 javadoc,并让 IDE 在保存文件时负责添加 @Deprecated 注释。
This can be easily dealt with a good IDE.
Eclipse Neon, for eg. automatically adds @Deprecated annotation, when I create a javadoc @deprecated on a method or field.
So I simply write the javadoc with the appropriate explanation and let the IDE take care of adding the @Deprecated annotation, the minute I save the file.