Amol Pawar

In Kotlin, annotations can target multiple elements of a declaration — such as a field, getter, or constructor parameter. When you apply an annotation without explicitly specifying a use-site target (e.g., @MyAnnotation instead of @field:MyAnnotation), Kotlin tries to infer the most appropriate placement.

This default behavior often works well — but in some cases, especially when interoperating with Java frameworks, it can produce unexpected results. Let’s dive into how it works, and what’s changing with Kotlin 2.2.0.

Default Target Inference in Kotlin (Before 2.2.0)

If the annotation supports multiple targets (defined via its @Target declaration), Kotlin infers where to apply the annotation based on context. This is especially relevant for primary constructor properties.

annotation class MyAnnotation
class User(
    @MyAnnotation val name: String
)

In this case, Kotlin might apply @MyAnnotation to the constructor parameter, property, or field—depending on what @MyAnnotation allows.

Approximate Priority Order:

When multiple targets are applicable, Kotlin historically followed a rough order of priority:

1. param – Constructor parameter
2. property – The Kotlin property itself
3. field – The backing field generated in bytecode

But this is not a strict rule — the behavior varies by context and Kotlin version.

Interop with Java Frameworks: Why Target Matters

Kotlin properties can generate several elements in Java bytecode:

• A backing field
• A getter method (and setter for var)
• A constructor parameter (for primary constructor properties)

Java frameworks (like Jackson, Spring, Hibernate) often look for annotations in specific places — typically on the field or getter. If Kotlin places the annotation somewhere else (e.g., the property), the framework might not recognize it.

class User(
    @JsonProperty("username") val name: String
)

If @JsonProperty is placed on the property instead of the field, Jackson may not detect it correctly. The fix is to use an explicit target:

class User(
    @field:JsonProperty("username") val name: String
)

Kotlin 2.2.0: Refined Defaulting with -Xannotation-default-target

Kotlin 2.2.0 introduces a new experimental compiler flag:

-Xannotation-default-target=param-property

When enabled, this flag enforces a consistent and more predictable defaulting strategy, especially suited for Java interop.

New Priority Order:

1. param – If valid, apply to the constructor parameter
2. property – If param isn’t valid, and property is
3. field – If neither param nor property is valid, but field is
4. Error — If none of these are allowed, compilation fails

This makes annotation behavior more intuitive, especially when integrating with Java-based tools and frameworks.

The @all: Meta-Target (Experimental)

Kotlin 2.2.0 also introduces the experimental @all: use-site target, which applies an annotation to all applicable parts of a property:

• param (constructor parameter)
• property (Kotlin-level property)
• field (backing field)
• get (getter)
• set (setter, if var)

Example:

@all:MyAnnotation<br>var name: String = ""

This is equivalent to writing:

@param:MyAnnotation
@property:MyAnnotation
@field:MyAnnotation
@get:MyAnnotation
@set:MyAnnotation

Only the targets supported in the annotation’s @Target list will be applied.

Best Practices

Here’s how to work with Kotlin annotations effectively:

Conclusion

While Kotlin’s inferred annotation targets are convenient, they don’t always align with Java’s expectations. Starting with Kotlin 2.2.0, you get more control and predictability with:

• Explicit use-site targets
• A refined defaulting flag (-Xannotation-default-target)
• The @all: meta-target for multi-component coverage

By understanding and controlling annotation placement, you’ll avoid hidden bugs and ensure smooth Kotlin–Java interop.

Annotations are a powerful feature in Kotlin that let you add metadata to your code. Whether you’re working with frameworks like Spring, Dagger, or Jetpack Compose, or building your own tools, knowing how to apply annotations in Kotlin can drastically improve your code’s readability, structure, and behavior.

In this guide, we’ll walk through everything step by step, using real examples to show how annotations work in Kotlin. You’ll see how to use them effectively, with clean code and clear explanations along the way..

What Are Annotations in Kotlin?

Annotations are like sticky notes for the compiler. They don’t directly change the logic of your code but tell tools (like compilers, IDEs, and libraries) how to handle certain elements.

If you use @JvmStatic, Kotlin will generate a static method that Java can call without needing to create an object. It helps bridge Kotlin and Java more smoothly.?

object Utils {
    @JvmStatic
    fun printMessage(msg: String) {
        println(msg)
    }
}

This makes printMessage() callable from Java without creating an instance of Utils.

How to Apply Annotations in Kotlin

To apply an annotation in Kotlin, you use the @ symbol followed by the annotation’s name at the beginning of the declaration you want to annotate. You can apply annotations to functions, classes, and other code elements. Let’s see some examples:

Here’s an example using the JUnit framework, where a test method is marked with the @Test annotation:

import org.junit.*

class MyTest {
    @Test
    fun testTrue() {
        Assert.assertTrue(true)
    }
}

In Kotlin, annotations can have parameters. Let’s take a look at the @Deprecated annotation as a more interesting example. It has a replaceWith parameter, which allows you to provide a replacement pattern to facilitate a smooth transition to a new version of the API. The following code demonstrates the usage of annotation arguments, including a deprecation message and a replacement pattern:

@Deprecated("Use removeAt(index) instead.", ReplaceWith("removeAt(index)"))
fun remove(index: Int) { ... }

In this case, when someone uses the remove function in their code, the IDE will not only show a suggestion to use removeAt instead, but it will also offer a quick fix to automatically replace the remove function with removeAt. This makes it easier to update your code and follow the recommended practices.

Annotations in Kotlin can have arguments of specific types, such as primitive types, strings, enums, class references, other annotation classes, and arrays of these types. The syntax for specifying annotation arguments is slightly different from Java:

To specify a class as an annotation argument, use the ::class syntax:

When you want to specify a class as an argument for an annotation, you can use the ::class syntax.

@MyAnnotation(MyClass::class)

In this case, let’s say you have a custom annotation called @MyAnnotation, and you want to pass a class called MyClass as an argument to that annotation. In this case, you can use the ::class syntax like this: @MyAnnotation(MyClass::class).

By using ::class, you are referring to the class itself as an object. It allows you to pass the class reference as an argument to the annotation, indicating which class the annotation is associated with.

To specify another annotation as an argument, don’t use the @ character before the annotation name:

when specifying an annotation as an argument for another annotation, you don’t need to use the “@” symbol before the annotation name.

@Deprecated(replaceWith = ReplaceWith("removeAt(index)"))
fun remove(index: Int) { ... }

In the above example, the @Deprecated annotation. It allows you to provide a replacement pattern using the ReplaceWith annotation. In this case, you simply specify the ReplaceWith annotation without the “@” symbol when using it as an argument for @Deprecated .

By omitting the “@” symbol, you indicate that the argument is another annotation.

To specify an array as an argument, use the arrayOf function:

if you want to specify an array as an argument for an annotation, you can use the arrayOf function.

For example, let’s say you have an annotation called @RequestMapping with a parameter called path, and you want to pass an array of strings ["/foo", "/bar"] as the value for that parameter. In this case, you can use the arrayOf function like this:

@RequestMapping(path = arrayOf("/foo", "/bar"))

However, if the annotation class is declared in Java, you don’t need to use the arrayOf function. In Java, the parameter named value in the annotation is automatically converted to a vararg parameter if necessary. This means you can directly provide the values without using the arrayOf function.

To use a property as an annotation argument, you need to mark it with a const modifier:

In Kotlin, annotation arguments need to be known at compile time, which means you cannot refer to arbitrary properties as arguments. However, you can use the const modifier to mark a property as a compile-time constant, allowing you to use it as an annotation argument.

To use a property as an annotation argument, follow these steps:

1. Declare the property using the const modifier at the top level of a file or inside an object.
2. Initialize the property with a value of a primitive type or a String.

Here’s an example using JUnit’s @Test annotation that specifies a timeout for a test:

const val TEST_TIMEOUT = 100L

@Test(timeout = TEST_TIMEOUT)
fun testMethod() {
    // Test code goes here
}

In this example, TEST_TIMEOUT is declared as a const property with a value of 100L. The timeout parameter of the @Test annotation is then set to the value of TEST_TIMEOUT. This allows you to specify the timeout value as a constant that can be reused and easily changed if needed.

Remember that properties marked with const need to be declared at the top level of a file or inside an object, and they must be initialized with values of primitive types or String. Using regular properties without the const modifier will result in a compilation error with the message “Only ‘const val’ can be used in constant expressions.”

Best Practices for Using Annotations

Using annotations the right way keeps your Kotlin code clean and powerful. Here are some tips:

1. Use Target and Retention Wisely

• @Target specifies where your annotation can be applied: classes, functions, properties, etc.
• @Retention controls how long the annotation is kept: source code only, compiled classes, or runtime.

@Target(AnnotationTarget.FUNCTION)
@Retention(AnnotationRetention.RUNTIME)
annotation class LogExecutionTime

Use RUNTIME if your annotation will be read by reflection.

2. Keep Annotations Lightweight

Avoid stuffing annotations with too many parameters. Use defaults whenever possible to reduce clutter.

annotation class Audit(val user: String = "system")

3. Document Custom Annotations

Treat annotations like part of your public API. Always include comments and KDoc.

/**
 * Indicates that the method execution time should be logged.
 */
@Target(AnnotationTarget.FUNCTION)
@Retention(AnnotationRetention.RUNTIME)
annotation class LogExecutionTime

Example: Logging Execution Time

Let’s say you want to log how long your functions take to execute. You can create a custom annotation and use reflection to handle it.

@Target(AnnotationTarget.FUNCTION)
@Retention(AnnotationRetention.RUNTIME)
annotation class LogExecutionTime

class Worker {
    @LogExecutionTime
    fun doWork() {
        Thread.sleep(1000)
        println("Work done!")
    }
}

Now add logic to read the annotation:

fun runWithLogging(obj: Any) {
    obj::class.members.forEach { member ->
        if (member.annotations.any { it is LogExecutionTime }) {
            val start = System.currentTimeMillis()
            (member as? KFunction<*>)?.call(obj)
            val end = System.currentTimeMillis()
            println("Execution time: ${end - start} ms")
        }
    }
}

fun main() {
    val worker = Worker()
    runWithLogging(worker)
}

This will automatically time any function marked with @LogExecutionTime. Clean and effective.

Advanced Use Case: Dependency Injection with Dagger

In Dagger or Hilt, annotations are essential. You don’t write much logic yourself; instead, annotations do the work.

@Module
@InstallIn(SingletonComponent::class)
object NetworkModule {

    @Provides
    fun provideApiService(): ApiService {
        return Retrofit.Builder()
            .baseUrl("https://api.softaai.com")
            .build()
            .create(ApiService::class.java)
    }
}

Here, @Module, @Provides, and @InstallIn drive the dependency injection system. Once you learn how to apply annotations in Kotlin, libraries like Dagger become far less intimidating.

Conclusion

Annotations in Kotlin are more than decoration — they’re metadata with a purpose. Whether you’re customizing behavior, interfacing with Java, or using advanced frameworks, knowing how to apply annotations in Kotlin gives you a real edge.

Quick Recap:

• Use annotations to add metadata.
• Apply built-in annotations to boost interoperability and performance.
• Create your own annotations for clean, reusable logic.
• Follow best practices: target, retention, defaults, and documentation.

With the right approach, annotations make your Kotlin code smarter, cleaner, and easier to scale.

Kotlin is known for being expressive, concise, and fully interoperable with Java. But when working with annotations in Kotlin, especially when defining your own, you might encounter something called @Target. If you’re wondering what @Target in Kotlin is, why it matters, and how to use it effectively—this guide is for you.

Let’s break it down, step-by-step.

What Is @Target in Kotlin?

In Kotlin, @Target is a meta-annotation. That means it’s an annotation used to annotate other annotations. It specifies where your custom annotation can be applied in the code.

For example, can your annotation be used on a class? A function? A property? That’s what @Target defines.

Kotlin uses the AnnotationTarget enum to list all possible valid locations.

Basic Syntax:

@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
annotation class MyAnnotation

In this example, MyAnnotation can only be used on classes and functions.

Why @Target in Kotlin Matters

Without @Target, your custom annotation could be misused. Kotlin wouldn’t know where it should or shouldn’t be applied. That could lead to:

• Confusing code
• Compilation warnings or errors
• Unintended behavior, especially when interoperating with Java

By clearly defining usage points, you make your code more maintainable, readable, and safe.

Understanding AnnotationTarget Options

Kotlin gives you a range of options for @Target. Here are the most common ones:

You can use more than one if needed:

@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION, AnnotationTarget.CONSTRUCTOR)
annotation class AuditLog

This lets you use @AuditLog on multiple types of declarations.

Example: Creating a Custom Annotation

Let’s say you’re building a system where you want to mark certain functions as “experimental”.

Step 1: Define the Annotation

@Target(AnnotationTarget.FUNCTION)
@Retention(AnnotationRetention.RUNTIME)
annotation class ExperimentalFeature(val message: String = "This is experimental")

• @Target(AnnotationTarget.FUNCTION): Only allows this annotation on functions.
• @Retention(RUNTIME): Keeps the annotation at runtime (optional but useful).

Step 2: Use the Annotation

@ExperimentalFeature("Might be unstable in production")
fun newAlgorithm() {
    println("Running experimental algorithm...")
}

Step 3: Read the Annotation at Runtime (Optional)

fun checkExperimentalAnnotations() {
    val method = ::newAlgorithm
    val annotation = method.annotations.find { it is ExperimentalFeature } as? ExperimentalFeature

    if (annotation != null) {
        println("Warning: ${annotation.message}")
    }
}

This prints:

Warning: Might be unstable in production

Tips for Using @Target in Kotlin

1. Be specific: The more targeted your annotation, the less chance of misuse.
2. Use multiple targets wisely: Don’t overgeneralize.
3. Pair with @Retention: Decide whether your annotation should be available at runtime, compile time, or source level.
4. Think Java Interop: If you’re interoperating with Java, know that @Target in Kotlin maps to @Target in Java too.

Conclusion

@Target in Kotlin is more than just a syntactic detail. It controls how annotations behave, where they’re valid, and how your tools (including the compiler and IDE) handle them.

If you’re building libraries, frameworks, or just want clean annotation usage, understanding @Target in Kotlin is essential. With the right @Target settings, your custom annotations stay safe, purposeful, and powerful.

New to Kotlin and wondering what the @ symbol means? That symbol introduces Kotlin annotations — a simple yet powerful feature that adds useful metadata to your code, making it smarter, cleaner, and easier to manage.

This quick guide will show you what Kotlin annotations are, why they matter, and how to use them effectively. No complex jargon, just the essentials — all in under 10 minutes.

What Are Kotlin Annotations?

Annotations in Kotlin are a way to attach metadata to code elements such as classes, functions, properties, and parameters. Metadata is like extra information about the code that can be used by the compiler, libraries, or even runtime frameworks.

Think of Kotlin annotations as digital sticky notes. They’re not actual instructions for logic, but they tell tools how to treat your code.

@Deprecated("Use newFunction() instead", ReplaceWith("newFunction()"))
fun oldFunction() {
    println("This function is deprecated.")
}

Here,

• @Deprecated tells both the developer and the compiler that oldFunction() shouldn’t be used.
• ReplaceWith("newFunction()") offers a suggestion.

Pretty straightforward, right?

Why Use Kotlin Annotations?

Kotlin annotations let you:

• Communicate intent clearly (e.g., deprecate functions)
• Influence compiler behavior
• Hook into frameworks like Android or Spring
• Enable code generation tools

They’re also essential when working with Java interoperability, which is a key strength of Kotlin.

Built-in Kotlin Annotations You Should Know

1. @Deprecated

Used to mark something as outdated.

@Deprecated("Don't use this")
fun oldApi() {}

2. @JvmStatic

Useful when writing Kotlin code that will be used from Java.

companion object {
    @JvmStatic
    fun create() = MyClass()
}

This makes create() callable as a static method from Java.

3. @JvmOverloads

Generates Java-compatible overloads for functions with default parameters.

@JvmOverloads
fun greet(name: String = "World") {
    println("Hello, $name")
}

Java doesn’t support default arguments natively, so this helps bridge the gap.

4. @Target

Specifies where an annotation can be used (e.g., class, property, function).

@Target(AnnotationTarget.CLASS)
annotation class MyAnnotation

5. @Retention

Defines how long the annotation is kept: source, binary, or runtime.

@Retention(AnnotationRetention.RUNTIME)
annotation class Loggable

Runtime retention means reflection tools can access this annotation at runtime.

How to Create Your Own Kotlin Annotations

Creating custom Kotlin annotations is easy.

@Target(AnnotationTarget.FUNCTION)
@Retention(AnnotationRetention.RUNTIME)
annotation class LogExecutionTime

This annotation can now be used on functions where you want to measure execution time.

@LogExecutionTime
fun performTask() {
    // Some logic here
}

Of course, this is just a tag. You’d need reflection or an AOP (Aspect-Oriented Programming) tool to act on it.

Kotlin Annotations in Android Development

In Android, Kotlin annotations are everywhere. A few you’ve probably seen:

• @UiThread, @MainThread, @WorkerThread — indicate expected thread usage.
• @Nullable and @NonNull — help with null safety, especially in Java interop.
• @Parcelize — works with Kotlin’s Parcelize plugin to simplify Parcelable implementation.

@Parcelize
data class User(val name: String, val age: Int) : Parcelable

This eliminates boilerplate, making Android dev smoother.

Best Practices When Using Kotlin Annotations

• Be intentional. Don’t slap annotations on everything. Know what they do.
• Check retention policies. Source-retained annotations won’t be available at runtime.
• Avoid clutter. Annotations should clarify, not complicate.
• Test interop. If you’re writing code to be used in Java, test how annotations behave.

Conclusion

Kotlin annotations might seem like just extra syntax, but they play a powerful role in shaping how your code behaves, communicates, and integrates with other systems.

They reduce boilerplate, enforce contracts, and help the compiler help you.

Whether you’re building Android apps, writing libraries, or just learning the ropes, understanding Kotlin annotations will make you a stronger, more fluent Kotlin developer.