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

发布于 2024-10-18 04:07:38 字数 373 浏览 5 评论 0原文

目前,有两种方法可以在 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 技术交流群。

扫码二维码加入Web技术交流群

发布评论

需要 登录 才能够评论, 你可以免费 注册 一个本站的账号。

评论(5

甚是思念 2024-10-25 04:07:38

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

根据 Oracle 的 Java Annotations 教程

当某个元素被弃用时,还应该使用 Javadoc @deprecated 标记对其进行记录...

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:

When an element is deprecated, it should also be documented using the Javadoc @deprecated tag...

十级心震 2024-10-25 04:07:38

来自马口

注意:Java 语言规范
要求编译器发出警告
当类、方法或字段
用@Deprecated注释标记
被使用。不需要编译器
通过 Java 语言规范
当类、方法、
或标有 @deprecated 的字段
访问 Javadoc 标签,尽管
Sun 编译器目前这样做。

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

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

From the horse's mouth:

NOTE: The Java Language Specification
requires compilers to issue warnings
when classes, methods, or fields
marked with the @Deprecated annotation
are used. Compilers are not required
by the Java Language Specification to
issue warnings when classes, methods,
or fields marked with the @deprecated
Javadoc tag are accessed, although the
Sun compilers currently do so.

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.

孤独患者 2024-10-25 04:07:38

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

一个例子如下:

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

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:

/**
* @deprecated We dont need this Method because ...
*/
@Deprecated
public void doStuff(){..}
寒尘 2024-10-25 04:07:38

您应该指定两者。

该注释让编译器知道它并在使用该方法时触发警告。
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!

穿越时光隧道 2024-10-25 04:07:38

一个好的 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.

~没有更多了~
我们使用 Cookies 和其他技术来定制您的体验包括您的登录状态等。通过阅读我们的 隐私政策 了解更多相关信息。 单击 接受 或继续使用网站,即表示您同意使用 Cookies 和您的相关数据。
原文