没有什么事情比看到一个没有任何说明的@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. zoj 3229 Shoot the Bullet(有源汇上下界最大流)

    Shoot the Bullethttp://acm.zju.edu.cn/onlinejudge/showProblem.do?problemId=3442 Time Limit: 2 Second ...

  2. 782B. The Meeting Place Cannot Be Changed 二分 水

    Link 题意:给出$n$个坐标$x_i$,$n$个速度$v_i$问使他们相遇的最短时间是多少. 思路:首先可肯定最终相遇位置必定在区间$[0,max(x_i)]$中,二分最终位置,判断左右部分各自所 ...

  3. Python学习笔记(补充)Split 用法

    >>> u = "www.doiido.com.cn" #使用默认分隔符 >>> print u.split() ['www.doiido.co ...

  4. HDU 2191 珍惜现在,感恩生活 (dp)

    题目链接 Problem Description 急!灾区的食物依然短缺! 为了挽救灾区同胞的生命,心系灾区同胞的你准备自己采购一些粮食支援灾区,现在假设你一共有资金n元,而市场有m种大米,每种大米都 ...

  5. HDU 5995 Kblack loves flag (模拟)

    题目链接 Problem Description Kblack loves flags, so he has infinite flags in his pocket. One day, Kblack ...

  6. APP爬虫之Appium使用

    一.安装环境 Appium安装(windows版) 一.安装node.js 1.到官网下载node.js:https://nodejs.org/en/download/ 2.获取到安装文件后,直接双击 ...

  7. CRF++进行中文分词实例

    工具包:https://taku910.github.io/crfpp/#tips 语料:http://sighan.cs.uchicago.edu/bakeoff2005/ 安装: 1)下载linu ...

  8. Qualcom QMI系列-基本知识介绍(转)

    1 引言1.1 编写目的       介绍Qualcom QMI 基本知识,API使用,设计原理,基于QMI的RemoteEfs(NV)分析1.2 阅读建议       高通平台入门1.3 参考资料 ...

  9. linux常用命令一些解释

    ls 命令是linux下最常用的命令.ls命令就是list的缩写缺省下ls用来打印出当前目录的清单如果ls指定其他目录那么就会显示指定目录里的文 件及文件夹清单. 通过ls 命令不仅可以查看li ...

  10. 003_循环(loop), 递归(recursion), 遍历(traversal), 迭代(iterate)的区别

    表示“重复”这个含义的词有很多, 比如循环(loop), 递归(recursion), 遍历(traversal), 迭代(iterate). 循环算是最基础的概念, 凡是重复执行一段代码, 都可以称 ...