Understanding Deprecation.
As newer versions of systems are rolled out every day, more powerful and useful functions, APIs, methods, classes are developed in the process, thereby rendering some implementation obsolete. In software development, when a function or an implementation becomes obsolete, it is not advisable to outrightly delete or yank it out of the system completely. It undergoes the process of deprecation.
Deprecating a method, class or function is a way of communicating to ( or warning ) others that such function will no longer be supported in future releases and hence discourage usage. This is essentially important when building a module, library that another system depends on or when making important changes to a function in a project you are contributing to.
It is a rich experience to let other developers know when a method is deprecated, why it is deprecated and importantly, what new options to explore. It is important to answer these 3 questions before deprecating a method, function or an entire API.
When: should talk about how long before the method is eventually taken out of the codebase. Also, When can signify an indication.
Why addresses why the method or API is deprecated. Users need to know what changes or improvements warrant the deprecation of an existing method.
What, should give insight or direction into the next steps. It should introduce new implementation or points, developers, to alternatives.
As of API, Level 26 in Android, 133 API of a total of 4478 API is marked as deprecated. This is 14 higher than the deprecated API in Level 25. This shows that developers keep deprecating old APIs to replace them with better ones and this circle continues. As of 2018, around 70% of deprecated Android APIs have comments on the reason for deprecation and also with replacement messages. This means 30% are deprecated without answering What Next.
Using a deprecated method doesn’t necessarily mean your code wouldn’t run but it can translate to:
- There are better ways to implement the deprecated API
- The deprecated approach might not be supported in future releases, so, look for alternatives
Every time I discover that a preferred solution is deprecated, I tend to look for answers by asking When the deprecation occurred and when will it be taken out completely, Why is this deprecated and finally, what are my new options. Often, you can quickly find a solution by searching on google but not in all cases.
Going forward, I will be taking a look into deprecated android Api’s and answering the following questions.
- When
- Why
- What next.
I will be discussing each discovery with one or two android developers and sharing the answers via this channel as a new post. The goal is not to just answer the questions about when, why and what next, but to share what we think about new alternatives, issues with deprecated implementation and provide other helpful information about the exercise.
With this, I also hope to enlighten maintainers of open source projects about the importance of following best practices when making changes that might affect so many dependent systems.
Because systems keep evolving, an open-source project that is not actively maintained is obsolete overtime and probably sitting on lots of deprecated APIs, making a change or upgrade catastrophic and making backward compatibility difficult to attain.
Here are the answers to a few questions you might have about deprecation.
How do I know when a method is deprecated?
Most IDE’s supports styling for identifying deprecated methods. Popular styling I know is stroking the deprecated API. Note that this might defers depending on the styling of your IDE.
Also, if you are taking a look at the method, it will be marked with the annotation @deprecated
How do I deprecate a method?
Deprecation is not the only applicable to a method. Here’s the supported scope in Kotlin and Java.
@Target({ElementType.CONSTRUCTOR, ElementType.FIELD, ElementType.LOCAL_VARIABLE, ElementType.METHOD, ElementType.PACKAGE, ElementType.PARAMETER, ElementType.TYPE})
public @interface Deprecated {
}You can simply deprecate a class, method or variable by annotating with like so:
/** @deprecated */
@Deprecated
public void setDrawingCacheQuality(int quality) {
throw new RuntimeException("Stub!");
}When should I deprecate an API?
When you design an API, carefully consider whether it supersedes an old API. If it does, and you wish to encourage developers (users of the API) to migrate to the new API, then deprecate the old API. Valid reasons to deprecate an API include:
It is insecure, buggy, or highly inefficient
It is going away in a future release
It encourages bad coding practices
Deprecation is a reasonable choice in all these cases because it preserves “backward compatibility” while encouraging developers to change to the new API. Also, the deprecation comments help developers decide when to move to the new API, and so should briefly mention the technical reasons for deprecation.
It is not necessary to deprecate individual member fields (properties) of a deprecated class, unless of course you want to explain a specific point about a property.
Do I get notified if a method, class or an API is deprecated?
Some open-source project provides deprecation notice. I have received notice via mails from Github about APIs that have been deprecated but usage is found on my codebase.
At the time of this writing, I don’t know of any too Github tool that notifies developers about newly deprecated functions in their codebase.
For really important changes in Andriod, I am sure you will find a warning on the console while building application dependent deprecated APIs that have been scheduled to change.
Also, there are lint checks for deprecated APIs usage in android. Unless you suppress this check, you will be noticed of such usage. So please, watch out for it.
For open-source maintainers, I suggest a stricter lint rule to keep everything in check and possibly a tool notifies developers via email if their codebase reference deprecated APIs. GitHub handles this beautifully.
What happens if the suggested alternative is not available to older versions?
Not all solutions are backward compatible. Why APIs might be deprecated, an alternative solution might not be possible on the older system. This means just replacing the old implementation with the new one wouldn’t suffice. For cases like this, employ the Branching technique. This means you still use the deprecated method for the older system but the new alternative is used in the new system. All that is required is to determine what system is running your application.
private void checkRunTimePermission() {
String[] permissionArrays = new String[]{Manifest.permission.CAMERA, Manifest.permission.WRITE_EXTERNAL_STORAGE};
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
requestPermissions(permissionArrays, 11111);
} else {
// not something to consider in the older version
}
}What happens if I continue using Deprecated methods?
- The code would continue running as it is until the method is removed from SDK. If you are using a deprecated method then you must keep track of removed APIs whenever you upgrade to the newest SDK.
- If you don’t want a change at all then check for the reason behind deprecation. If deprecation is because of performance issues then you might consider upgrading to the newest methods.
- Confirm that the deprecated method doesn’t affect the majority of your users. If it does, you will be deeply affected when it is removed.
- Confirm if the new alternative is backward compatible. If it is not, employ the branching technique. If it is, you might be better off switching immediately.
Please drop more questions if you have any or reach out if you are an android developer willing to share your experience and insight on a deprecated Android API.
📝 Save this story in Journal.
👩💻 Wake up every Sunday morning to the week’s most noteworthy stories in Tech waiting in your inbox. Read the Noteworthy in Tech newsletter.
