Previous | Next | Trail Map | To 1.1 -- And Beyond! | Migrating to 1.1


What Does Deprecation Mean?

You might have heard of the term "self-deprecating humor." It describes humor that minimizes one's own importance.

Similarly, when a class or method is deprecated, it means that the class or method is no longer considered important. It is so unimportant, in fact, that it should no longer be used at all, as it might well 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, API documentation can warn the user against using the deprecated item and tell the user how to avoid doing so. To mark API as deprecated, the implementer of the API uses a special tag in doc comments: @deprecated.


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


Previous | Next | Trail Map | To 1.1 -- And Beyond! | Migrating to 1.1