Tackle tech debt with @Deprecated annotation

Let’s face it, we all have to tackle tech debt, because, things are going so fast in IT, we always try to catch up with the latest trends, the latest tech, the latest best practices, and we love that. Change is good, it’s evolution.

It takes some efforts to research and adapt existing code to the “new way”, the new “best practice”, you name it. And what if we could make this process a little bit easier?

Deprecated on Steroids with ReplaceWith

With Kotlin, we’ve got the @Deprecated annotation, introducing a new parameter, ReplaceWith which essentially allows you to replace old code with shiny new.

Signature change

Let’s start easy with a signature change. Let’s say we’ve got this function:

fun myFunction(param1: String, param2: String)

and we want to deprecate it in favour to:

fun myFunction1(param1: String)

We can then have the following @Deprecated annotation:

@Deprecated("please use myFunction1", ReplaceWith("myFunction1(param1)"))

This is going to change the function name and keep only param1

using alt-return, we can replace one instance

With option+return, you can get the IDE to propose suggestions for replacing the deprecated myFunction , it will rename the function and remove the second parameter while keeping the first one.

Advanced replacing with imports

Let’s go with something a bit more sophisticated. In the previous example we’ve seen that we can rename the function and re-use parameters.

Function’s parameters can actually be re-used to match the new function requirement.

fun myFunction(param1: String, param2: String)

and we want to migrate to the following:

fun myFunction2(param1: String, param2: String, param3: String)

by using this @Deprecated annotation:

@Deprecated("please use MyClass1.myFunction2",
    replaceWith = ReplaceWith("MyClass1.myFunction2(param2, param1, (param1+param2).capitalize() )",
        imports = ["com.package.MyClass1"]
    ))

As you can see, we have inverted param1 and param2 , in addition param3 is actually processed using param1 and param2 .

We are also calling this function with MyClass1 rather than MyClass, and therefore we need to import it.

We can see that a and b have been inverted. they have also been re-used for the third parameter. And last but not least, MyClass1 has been imported.

Classes, Properties, and a lot more

According to the @Deprecated annotation definition, it can be use in a large variety of context.

@Target(CLASS, FUNCTION, PROPERTY, ANNOTATION_CLASS, CONSTRUCTOR, PROPERTY_SETTER, PROPERTY_GETTER, TYPEALIAS)

Replace everywhere!

Now imagine, you are migrating a function that is used across your entire project, potentially in hundreds instances across dozens or even hundreds files.

It would be a very tedious process to go in every files and replace with the new implementation.

Fortunately, Android Studio allow us to do just that in one click!

replace in the entire project in just one click!

Transition helped with Deprecation Levels

Because we don’t always want to go big bang with the new API, @Deprecated offers 3 level of deprecation

WARNING: deprecated element shows striked in the IDE and trigger a warning at compile time.

ERROR: deprecated element will show as an error in the IDE and trigger an error at compile time

HIDDEN: won’t be accessible (like on auto-complete) and trigger Unresolved Reference error at compile time. Just like it doesn’t exists

Does it works with Java?

Yes it does! the syntax is slightly different, see below

@Deprecated(message = "replace with myFunc2()", replaceWith = @ReplaceWith(expression = "myFunc2()", imports = ""), level = DeprecationLevel.ERROR)

You will have to provide explicitly the name of the parameters, such as message or expression. In addition, you will use @ReplaceWith annotation.

It’s your turn now!

In this article we have seen how powerful the @Deprecated annotation provided by Kotlin can help migrate old code to shiny new one. It’s an excellent tool to use when tackling Tech Debt.

I hope you enjoyed reading this article and that you will be able to update your code very soon with brillant new APIs.

If you are into Android Development, have a look the ADN: Android Developer News 🤖, and keep up with Android Development trends!