如何正确地使用Java的@deprecated标注
没有什么事情比看到一个没有任何说明的@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标注的更多相关文章
- 全网最详细的IDEA里如何正确新建普通的Java web项目并发布到Tomcat上运行成功【博主强烈推荐】(类似eclipse里同一个workspace下【一个子项目】并存)(图文详解)
不多说,直接上干货! 首先,大家要明确,IDEA.Eclipse和MyEclipse等编辑器之间的新建和运行手法是不一样的. 如果是在Myeclipse里,则是File -> new -> ...
- 全网最详细的Eclipse里如何正确新建普通的Java web项目并发布到Tomcat上运行成功【博主强烈推荐】(图文详解)
不多说,直接上干货! 首先,大家要明确,IDEA.Eclipse和MyEclipse等编辑器之间的新建和运行手法是不一样的. 如果是在Myeclipse里,则是File -> new -> ...
- 全网最详细的MyEclipse里如何正确新建普通的Java web项目并发布到Tomcat上运行成功【博主强烈推荐】(图文详解)
不多说,直接上干货! 首先,大家要明确,IDEA.Eclipse和MyEclipse等编辑器之间的新建和运行手法是不一样的. 如果是在eclipse里,则是File -> new -> ...
- Redis实现分布式锁的正确使用方式(java版本)
Redis实现分布式锁的正确使用方式(java版本) 本文使用第三方开源组件Jedis实现Redis客户端,且只考虑Redis服务端单机部署的场景. 分布式锁一般有三种实现方式: 1. 数据库乐观锁: ...
- java中“@Deprecated”的意思
例如:Java内在的File类中有如下方法 @Deprecatedpublic URL toURL() throws MalformedURLException {return new URL(&qu ...
- Java中@Deprecated、@SupressWarning、@Override的作用
Annotation注解在 Java 中有着很广泛的,他是做为一种标识 为javac所识别.每一个注解 都对应这一个Java类 在java.lang包中 有三个注解 分别是 Deprecated ...
- 如何正确的把 Java 数组 Array 转为列表 List
最近想把 java 数组转成 List,网上普遍的答案都是 Arrays.asList: String[] a = new String[] {"hello", "wor ...
- 如何正确的在java web配置数据池
在tomcat context.xml中配置数据 <Context reloadable="true"> <!-- Default set of monitore ...
- 正确的停止java中的线程
stop()方法不是一个正确的停止线程方法. 正确的停止方法:设置退出旗标
随机推荐
- zoj 3229 Shoot the Bullet(有源汇上下界最大流)
Shoot the Bullethttp://acm.zju.edu.cn/onlinejudge/showProblem.do?problemId=3442 Time Limit: 2 Second ...
- 782B. The Meeting Place Cannot Be Changed 二分 水
Link 题意:给出$n$个坐标$x_i$,$n$个速度$v_i$问使他们相遇的最短时间是多少. 思路:首先可肯定最终相遇位置必定在区间$[0,max(x_i)]$中,二分最终位置,判断左右部分各自所 ...
- Python学习笔记(补充)Split 用法
>>> u = "www.doiido.com.cn" #使用默认分隔符 >>> print u.split() ['www.doiido.co ...
- HDU 2191 珍惜现在,感恩生活 (dp)
题目链接 Problem Description 急!灾区的食物依然短缺! 为了挽救灾区同胞的生命,心系灾区同胞的你准备自己采购一些粮食支援灾区,现在假设你一共有资金n元,而市场有m种大米,每种大米都 ...
- HDU 5995 Kblack loves flag (模拟)
题目链接 Problem Description Kblack loves flags, so he has infinite flags in his pocket. One day, Kblack ...
- APP爬虫之Appium使用
一.安装环境 Appium安装(windows版) 一.安装node.js 1.到官网下载node.js:https://nodejs.org/en/download/ 2.获取到安装文件后,直接双击 ...
- CRF++进行中文分词实例
工具包:https://taku910.github.io/crfpp/#tips 语料:http://sighan.cs.uchicago.edu/bakeoff2005/ 安装: 1)下载linu ...
- Qualcom QMI系列-基本知识介绍(转)
1 引言1.1 编写目的 介绍Qualcom QMI 基本知识,API使用,设计原理,基于QMI的RemoteEfs(NV)分析1.2 阅读建议 高通平台入门1.3 参考资料 ...
- linux常用命令一些解释
ls 命令是linux下最常用的命令.ls命令就是list的缩写缺省下ls用来打印出当前目录的清单如果ls指定其他目录那么就会显示指定目录里的文 件及文件夹清单. 通过ls 命令不仅可以查看li ...
- 003_循环(loop), 递归(recursion), 遍历(traversal), 迭代(iterate)的区别
表示“重复”这个含义的词有很多, 比如循环(loop), 递归(recursion), 遍历(traversal), 迭代(iterate). 循环算是最基础的概念, 凡是重复执行一段代码, 都可以称 ...