How and When to Deprecate APIs - JDK 5 Documentation v1.2.2, Java 2 SDK 英文文档

How and When To Deprecate APIs (based on a writeup by John Rose) Maintained by doug.kramer@sun.com

Deprecation Home Page

Contents

• What "Deprecated" means
• When to Deprecate
• What happens when an API is Deprecated
• How to Deprecate

What "Deprecated" means

You may have heard the term, "self-deprecating humor". That is humor that minimizes your importance. A deprecated class or method is like that. It is no longer important. It is so unimportant, in fact, that it should no longer be used at all, as it will probably cease to exist in the future.

The need for deprecation comes about because, as a class evolves, its API changes. Methods are renamed for consistency. New and better methods are added. Attributes change. But making such changes introduces a problem. You need to keep the old API around until people make the transition to the new one, but you don't want developers to continue programming to the old API.

The ability to mark a class or method as "deprecated" solves the problem. Existing classes that use the old API continue to work, but the compiler can issue a warning when it finds references to deprecated items. Meanwhile, the API comments can warn the user against using the deprecated item and tell the user how to avoid doing so. The @deprecated tag achieves these goals.

Note: "Deprecated" and "depreciated" are not same. "Depreciated" is a financial term that means "lowered value". Although the meanings are similar, classes and methods are deprecated, not depreciated.

When to Deprecate

Designers of new APIs should carefully consider whether they are superseding old APIs. For each such API, if they wish to encourage users of the old previous API to migrate to the new API, they should add a deprecation paragraph to the documentation comment. Empty deprecation paragraphs are bad form, because they do not help the user fix the warnings that arise from the deprecation.

Valid reasons for wishing one's users to migrate to the new API include: - the old API is insecure, buggy, or highly inefficient - the old API is going away in a future release - the old API encourages very bad coding practices Not all of these reasons are of equal weight, yet deprecation is a reasonable (though not mandatory) choice in all these cases. Therefore, the use of deprecated APIs can never be made a hard error by default. Also, the deprecation comments need to help the user decide when to move to the new API, and so should briefly mention the technical reasons for deprecation.

What happens when an API is Deprecated

In parallel with the access-checking logic for classes and members, the compiler looks for deprecated attributes of classes and members being accessed, and issues warnings when the deprecated classes or members are used.

Note: A deprecation warning is suppressed if the compilation unit containing the deprecation is being compiled at the same time as the compilation unit using the deprecated class or member. This allows legacy APIs to be built without warnings. There currently is no other way to suppress the deprecation warnings.

JavaDoc also pays special attention to @deprecated tags when generating html files. Javadoc parses the entire paragraph following the @deprecated tag and moves it to the front of the description, placing it in italics and preceding it with a warning, "Note: foo is deprecated", in bold. It also adds "Deprecated" in bold to any index entries mentioning the deprecated entity.

How to Deprecate

To deprecate a class or method, use the @deprecated tag, as explained in How to Write Doc Comments for JavaDoc. The paragraph following the @deprecated tag should explain why the item has been deprecated and suggest how the user can avoid using it.

It is not necessary to deprecate individual members of a deprecated class, unless of course the programmer wants to explain some specific point about one member.

Note: Deprecation applies to classes and to individual members, not to their names. It is possible for a single method to have deprecated and non-deprecated overloadings. It is possible for a non-deprecated member to hide or override a deprecated one, which removes deprecation. It is the responsibility of the programmer to deprecate overrides of a deprecated method, if in fact they should be deprecated.

It is probably not good to specifically mention a timetable for phase-out of the deprecated API; this is a business decision that needs to be communicated other ways.

When a feature is deprecated, it is a good idea to notify the engineering organization of this fact, so that other engineers can respond to the change (pro or con) in a timely manner.