没有什么事情比看到一个没有任何说明的@deprecated标注更让人愤怒的事情了。这种做法只能让人困惑,我到底还要不要用这个已经‘废弃’的方法?如果开发者不希望某个方法再被人用的话,就要好好地为@deprecated标注写说明。这篇文章就讨论了正确地使用@deprecated 标注需要遵守的一些规则。

什么是使用@Deprecated标注的规则?

Rule #1: do Javadoc how not to

每当你弃用某方法时,创建JavaDoc告诉其他程序员如何不再使用这个方法。不要只说“这个方法废弃了,不要用它”。因为这就是废弃标注和JavaDoc中@deprecated的字面意义,完全没有必要再重复一遍。Java开发人员作为目标受众,都知道deprecation的意思。

命名新的方法,取代旧有的。(使用@link标注!)这可能还不够,新的方法对应的文档将解释如何使用它。不要在JavaDoc中重复(其字面意义),文档也应遵从DRY原则。另一方面你可能想要描述怎样替换掉旧方法的调用,你可以就重构的细节给出提示。

Rule #2: do not Javadoc how to

移除过时的JavaDoc文档。有些人可能争辩:维护遗留代码的用户可能还会需要这些文档。事实上,他们使用的是旧版本库中的旧版本方法。旧版本的文档仍旧存在那里,像被刻在石头上(更确切的说是刻在资源仓库的某个版本上)。含有被废弃掉的方法的实际版本不应包含过时的描述文档,那会鼓励程序员去继续使用。对于废弃的方法,只有一种用法:不去用。JavaDoc应该被实时描述,如同rule#1所述。

Rule #3: 不要在JavaDoc中解释

不要在JavaDoc中解释为什么方法被废弃了。你是一个可靠的的开发,这是你的决定,你的选择,其他人只能忍着。如果愿意,可以写一篇博客记录这次调整的决策背景。这可能有帮助,但它不应被写在JavaDoc中。

JavaDoc的Deprecated API专用来讲解如何不再使用。 重点是如何(how)。而不是“为什么不再使用它(why)”。

Rule #4: do deprecate

如果你觉得需要弃用一方法,那就去做吧!如果你害怕你的用户,或不想因你废弃掉一些方法导致你用户体验更加痛苦,这个决定将让你自己痛苦。尽你所能去让API维持长久的稳定。但如果有需要被废弃的:立刻扔掉它。不要因“为何当初设计API时没有考虑到未来的变动”而感到愧疚。没有人能完美的预见未来。毕竟,如果你知道未来,生活就无趣了。

原文链接: javacodegeeks
翻译: ImportNew.com - dust_jead
译文链接: http://www.importnew.com/10113.html

如何正确地使用Java的@deprecated标注的更多相关文章

  1. 全网最详细的IDEA里如何正确新建普通的Java web项目并发布到Tomcat上运行成功【博主强烈推荐】(类似eclipse里同一个workspace下【一个子项目】并存)(图文详解)

    不多说,直接上干货! 首先,大家要明确,IDEA.Eclipse和MyEclipse等编辑器之间的新建和运行手法是不一样的. 如果是在Myeclipse里,则是File -> new -> ...

  2. 全网最详细的Eclipse里如何正确新建普通的Java web项目并发布到Tomcat上运行成功【博主强烈推荐】(图文详解)

    不多说,直接上干货! 首先,大家要明确,IDEA.Eclipse和MyEclipse等编辑器之间的新建和运行手法是不一样的. 如果是在Myeclipse里,则是File -> new -> ...

  3. 全网最详细的MyEclipse里如何正确新建普通的Java web项目并发布到Tomcat上运行成功【博主强烈推荐】(图文详解)

    不多说,直接上干货! 首先,大家要明确,IDEA.Eclipse和MyEclipse等编辑器之间的新建和运行手法是不一样的. 如果是在eclipse里,则是File -> new ->  ...

  4. Redis实现分布式锁的正确使用方式(java版本)

    Redis实现分布式锁的正确使用方式(java版本) 本文使用第三方开源组件Jedis实现Redis客户端,且只考虑Redis服务端单机部署的场景. 分布式锁一般有三种实现方式: 1. 数据库乐观锁: ...

  5. java中“@Deprecated”的意思

    例如:Java内在的File类中有如下方法 @Deprecatedpublic URL toURL() throws MalformedURLException {return new URL(&qu ...

  6. Java中@Deprecated、@SupressWarning、@Override的作用

    Annotation注解在 Java 中有着很广泛的,他是做为一种标识 为javac所识别.每一个注解 都对应这一个Java类  在java.lang包中 有三个注解  分别是 Deprecated  ...

  7. 如何正确的把 Java 数组 Array 转为列表 List

    最近想把 java 数组转成 List,网上普遍的答案都是 Arrays.asList: String[] a = new String[] {"hello", "wor ...

  8. 如何正确的在java web配置数据池

    在tomcat context.xml中配置数据 <Context reloadable="true"> <!-- Default set of monitore ...

  9. 正确的停止java中的线程

    stop()方法不是一个正确的停止线程方法. 正确的停止方法:设置退出旗标

随机推荐

  1. 2017北京国庆刷题Day5 morning

    期望得分:0+60+60=120 实际得分:0+30+60=90 令g=gcd(X11,X12,X13……) 则行列式可能为D的充要条件为g|D 1.g|D为必要条件: 由定义来算行列式的时候,每一项 ...

  2. Elasticsearch Java API 配置测试

    Elasticsearch1.X,2.X,5.X随着版本的迭代,除了系统升级,Java API也做了相对较大的调整,也就是说,1.X的API在2.X以及5.X乃至未来6.X版本都不是通用的. 本例子使 ...

  3. Anniversary party(树形dp入门)

    Anniversary party Time Limit: 2000/1000 MS (Java/Others)    Memory Limit: 65536/32768 K (Java/Others ...

  4. 20155117王震宇 2016-2017-2 《Java程序设计》第八周学习总结

    教材学习内容总结 正则表达式 正则表达式是记录文本规则的代码 元字符 ^ :^会匹配行或者字符串的起始位置,有时还会匹配整个文档的起始位置. $ :$会匹配行或字符串的结尾. \b :不会消耗任何字符 ...

  5. 模型稳定度指标PSI与IV

    由于模型是以特定时期的样本所开发的,此模型是否适用于开发样本之外的族群,必须经过稳定性测试才能得知.稳定度指标(population stability index ,PSI)可衡量测试样本及模型开发 ...

  6. webgote的例子 数据库与sql注入的相关联系(1)

    大家好我是时光凉春衫薄 之前将讲的sql注入有点随便了我同事也觉得有些地方看不懂,往后的几天我尽量写的细一点.尽可能让大家能看懂.(新手出道大佬多多指教.欢迎评论批评.) 数据库与sql注入的相关联系 ...

  7. python并发编程之multiprocessing进程(二)

    python的multiprocessing模块是用来创建多进程的,下面对multiprocessing总结一下使用记录. 系列文章 python并发编程之threading线程(一) python并 ...

  8. 【swupdate文档 五】从可信的来源更新镜像

    从可信的来源更新镜像 现在越来越重要的是,设备不仅要能安全地进行更新操作, 而且要能够验证发送的图像是否来自一个已知的源, 并且没有嵌入恶意软件. 为了实现这个目标,SWUpdate必须验证传入的镜像 ...

  9. [SVN技巧]代码提交中遇到的两个问题及其解决方案

    前言 SVN在使用的过程中会遇到各种各样的问题,小黑在最近的使用中,遇到如下的两个问题,这里贴出来供大家参考 问题记录 SVN在源码仓库中不存在,导致无法删除和上传 问题提示: Working cop ...

  10. window server 2008 配置ftp并实现用户隔离

    文件传输协议(FTP)是一个标准的网络协议,用于传输计算机文件从一台主机到另一台主机通过TCP为基础的网络,如互联网. -WIKI百科 好久没更新教程了, 今天更新一下博客,也不知道会不会有人看….本 ...