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.