Why do certain code elements (classes, methods etc.) in public APIs get deprecated over time?

Question

Today our professor discussed with the class that what "class X or method X get deprecated" means? From what I understood, it means, for example, that we are not going to get that method or class in the Java API in the future so we better use another method or class instead of this class. Then comes another question, why do they get deprecated?

My guess for this question was that it is because the Java API developers may find those classes or methods are using an algorithm which is not efficient and they replace them with another class(es) or method(s) which are more efficent. But the professor wasn't happy with my answer and told me to google. And I couldn't find anything. Can you please tell me why the classes get deprecated?

Answer 1

The usual reason for deprecating a class or method is because it's difficult to use or has behavior that is no longer considered "good," not because it's been replaced with a more efficient implementation.

For example, the java.util.Date class has a constructor that takes three integer values, for year, month, and day. On the surface, this seems a simple and reasonable constructor. However, it creates a Date object that represents that midnight local time for that year/month/day. So, assuming an application that is run in multiple locations, you can get into a situation where you've called this constructor with the same values, but get different results. Which is particularly bad if you then store that date in a worldwide-accessible database.

Deprecated classes/methods rarely get removed -- that Date constructore, for example, has been deprecated almost since Java was publicly released, yet it's still here 15 years later. The reason is backward compatibility: you don't want to break existing code, even if that code should be rewritten. At some point, however, breaking backwards compatibility might be a better choice than hauling around a lot of deprecated methods.

Answer 2

I think your first guess pretty much got it. Assuming s/depreciated/deprecated/ anyway.

Generally speaking, functions are deprecated when there is a better way of accomplishing what they were originally used for. This happens across all languages and many projects, and can apply to syntax as well as functions and methods.

Answer 3

It is because the Java API developers may find those classes or methods are using an algorithm which is not efficient and they replace them with another class(es) or method(s) which are more efficent.

This may be one reason. Another is that they may realise that some method/class is faulty, error-prone, difficult/unintuitive to use, or plainly broken.

Designing APIs is hard. Often the designers are under time pressure, in a new field, so they make decisions whose implications aren't fully understood at that time. Sometimes it turns out that such a decision has unexpected bad consequences. Then a better way is devised in the next API/framework/language release, and the old one may get deprecated.

Answer 4

Deprecation lets Java maintainers kill off a bad API while giving users time to migrate. By keeping the old and new APIs, you can upgrade the JVM with minimal changes in one step, and fix the deprecated API in a second project. It also functions as a warning to developers that a particular function is for compatibility with old unchangeable code and should not be used.

As for why, if it were just the algorithm being bad, you could fix it in the library without changing the API. Deprecation is for those times where the API itself was poorly designed. For example, consider strlen vs strnlen in C. Or the old API relied on assumptions about internal implementation of Java itself.

Answer 5

Because the developers of those classes, libraries and frameworks are also humans. They make mistakes, learn by doing and improve things over time. That means that they don't get some things right from the start and have to catch up in future releases.

Another part of the story is that it often requires a hands-on experience with a tool and large feedback from a vast community of users to understand the usage profile of the tool, its weak and strong sides, its most popular and less popular functions, parts of it that confuse users and cause them to misuse certain functions and produce bugs. Only based on that information does it become possible to optimize the tool and tailor it to the actual user needs.

Answer 6

Sometimes things get deprecated because they turn out to be unsafe, or because the implementation is causing problems elsewhere. For example, the standard C library function gets is the poster child for malware exploits, due to its inability to protect against buffer overflow. It was deprecated in the C99 standard, and appears to be gone completely from the proposed C1X standard. The mayhem that one little library call enabled is scarier than the prospect of breaking 35+ years of legacy code.

Answer 7

The answer you might be looking for is that APIs can not get changed. Once you release an api, it's there. Changing it would break existing code relying on it.

So instead of changing an API, the developers mark it as deprecated and create a new class/method.

This way old code keeps working while on the other hand better methods become available for code you write now or in the future.

I think that's what your professor is hinting at: deprecating and creating new methods instead of changing.