Java函数注释帮助,使用@Deprecated？

Question

场景:
Java 1.6

class Animal { 
    private String name; 
    ...  
    public String getName() { return name; }  
    ...
}

class CatDog extends Animal {
    private String dogName;
    private String catName;
    ...
    public String getDogName() { return dogName; }
    public String getCatName() { return catName; }
    public String[] getNames() { return new String[]{ catName, dogName }; }
    ...
    public String getName() { return "ERROR! DO NOT USE ME"; }
}

问题:
getName没有意义,不应该在这个例子中使用.我正在阅读@Deprecated注释.有更合适的注释方法吗？

问题:
A)使用此功能时(运行前)是否可以强制执行错误？
B)有没有办法为我将使用的注释方法显示自定义警告/错误消息？理想情况下,当用户将鼠标悬停在已弃用/错误函数上时.

Answer 1

通常,对于已经被较新版本的软件淘汰的方法,使用@Deprecated,但是为了与依赖于旧版本的代码的API兼容性而保留这些方法.我不确定它是否是在这种情况下使用的最佳标记,因为getName仍然被其他子类主动使用Animal,但它肯定会警告CatDog类的用户他们不应该调用该方法.

如果要在编译时使用该函数时导致错误,可以更改编译器选项,以考虑使用@Deprecated方法作为错误而不是警告.当然,您无法保证使用您的库的每个人都会设置此选项,并且我无法仅根据语言规范强制编译错误.从中删除方法CatDog仍然允许客户端调用它,因为客户端只是从超类调用默认实现Animal(可能你仍然希望包含该方法).

但是,当用户将鼠标悬停在已弃用的方法上时,当然可以显示自定义消息.Javadoc @deprecated标记允许您指定一个方法被弃用的原因的解释,当用户将鼠标悬停在像Eclipse这样的IDE中的方法时,它将弹出而不是通常的方法描述.它看起来像这样:

/**
 * 
 * @deprecated Do not use this method!
 */
 @Deprecated
 public String getName() {
     throw new UnsupportedOperationException();
 }

(注意,您可以使该方法的实现抛出异常,以保证如果用户在编译时没有注意到@Deprecated标记,他们肯定会在运行时注意到它).

Answer 2

弃用意味着该方法不应再使用,并且可能在将来的版本中删除.基本上就是你想要的.

是的,当有人试图使用该方法时,有一个简单的方法来获取编译错误:删除方法 - 这会导致链接时出现任何试图使用它的代码的错误,通常不建议出于明显的原因,但如果打破向后兼容性是一个非常好的理由,这是实现它的最简单方法.您还可以使方法签名不兼容(始终可行),但实际上最简单的解决方案通常是最好的.

如果你想在有人将鼠标悬停在方法上时自定义消息,请使用javadoc,这正是它的用途:

/**
     * @deprecated
     * explanation of why function was deprecated, if possible include what 
     * should be used.
     */

Answer 3

重构 User 类后，我们无法删除userGuid属性，因为它被移动应用程序使用。因此，我已将其标记为已弃用。好处是 IntellijIdea 等开发工具可以识别它并显示消息。

public User {
    ...

    /**
     * @Deprecated userGuid equals to guid but SLB mobile app is using user_guid.
     * This is going to be removed in the future.
     */
    @Deprecated
    public String getUserGuid() {
        return guid;
    }
}